ASA- L 9-I90bf,3 


n 



DNET 


A Communications Facility 
for 

Distributed Heterogeneous Computing 


o 

cr 


f*- 

m 

10 

O 

f-4 

<0 


1 


H 

m 

U 

<\j 

o 

c 

«•— t 

2T 

O 

o 



o 

o 

\ 

rn 

o 


FINAL REPORT 

Contract NAS 5 - 30085 


Digital Analysis Corporation 
t 1889 Preston White Drive 
Reston, Virginia 22091 
(703) 476-5900 


•J 5 

4 


3 uo 

CL ■- 

T. J) 

o >- 

ex: u — 

o 

< Ll. DO C 


UJ »— 

UJ Z 

Z -J Ll' 4J 

Q M O •* 

u c cr 

< or — 

^ u. u, c 

^ >— w 

nC co a. 1 

^ x a 

0 a +> 

^ H Q u ^ 

***^ ►*— UJ O it 

1 < h* a. ro 

a U 3 a 

u •— .tq a: 

I Z m ^ 

< rt — • 

W 3t h r. O 

< X oo C u 

i? Q *— < ■— c 

v U Q IL U 


SB I A RIGA 


TO. SBIR da t. turahed with SBIR right, under NASA Contra NAS5-300I 
^Gwnron. agree. to ure th* <*t. fa, Gorernmeo. pmpore, only, and 
pwpcwa) during .itch period with*. penmerian at the Contractor. eacrpt th 
b y myort c oreraore. Aha- the atotreud J-yeu period the Gownmtem 
pwptwe^ bte ie telieved from mi] diedooure protubitioa sal ' 
•ltaed to ay reproduction. od OK. due, to whole, or to put • 


('For 


NOTICE 

* c “P t * n “ <* •“ ««» <o be debrered under thw cootra 
"* Gv^rmnt (indudutg dwckwure far procurement 

tltY-frre l^ILT: i ^ k * Ur * prDh * M,om ' ■ uc4 n»y be daejored (or ure 

i^fae hoenre to are. utd to .tahorue other, to me on it. bebatt, thw due tor 
pliability tor unatahortzed ueed at thie dun ty third partial. TO. Notice .hall be 


C^ynghl l», Digital Analyri. Corporation 



DNET 


INTRODUCTION GUIDE 


Version: 124 

Print Date: 09/01/89 13:1437 
Module Name: intro.gui 


Digital Analysis Corporation 
1889 Preston White Drive 
Heston, Virginia 22091 






CONTENTS 


1. Abstract 

* + »#«» + «• 

2. Orga niza tion of the Remainder of this Introductory Guide 

3. Services Requested By NASA 

4. Overall Topology of DNET 

5. Defined Boundaries 

6. Interfaces to DNET 

7. DNET Implementation 

8. Major DNET Components 

9. Organization of the DNET Documentation ...... 



DAC Staff who contributed to DNET: 


Principal Investigator 
John Tole, Sc.D. 

Engineers: 

S. Nagappan 
J. Clayton 
P. Ruotolo 
C. Williamson 
H. Solow 


Acknowledgements: 

The DAC DNET project staff gratefully acknowledges the contributions of other persons and 
organizations to this effort. 

• Barry Jacobs and Shyam Salona of the DAVID project at NASA Goddard Space Flight Center 
(NASA-GSFC) were the principal NASA contacts for this project. Their support and interfaces 
with other NASA personnel greatly facilitated all aspects of DACs effort. Their understanding of 
the nature of this research also made the conduct of this project most pleasant for the project staff 
Their efforts are deeply appreciated. 

• The DNET interfaces to TCP/IP and DECnet are based in part on the ’NET code developed at 
Space Telescope Institute (STI). DNET also derives some of its design philosophy from the STI- 
NET system. DAC is grateful to STI for providing the NET code and for consultation on its use. 
Peter Shames and Steve Zeller of STI were especially helpful with information and access to STI 
resources. 

• Todd Butler of the NSSDC facility at NASA-GSFC provided much useful consultation and 
assistance on DECNET. 

• Jerome Bennett and Charles Cosner of the Data Flow Technology staff were unceasingly co- 
operative in resolving numerous questions and problems with the IAF and DFTNIC VAX machines 
at NASA-GSFC. This project could not have been completed without their assistance. 

• David Pipes and Randy Thompson provided valuable administrative assistance on the nssdcs and 
iuesnl SUN4 computers at NASA-GSFC. 

• Bob Wood and Sally Saucedo of DAC provided ongoing system administration which is greatly 
appreciated. 

• Chris Walters of Mitre Corporation offered important technical contributions on the configuration 
of an Ethernet System. 



1. Abstract 


This document describes DNET, a heterogeneous data communications networking facility. DNET 
allows programs operating on hosts on dissimilar networks to communicate with one another without 
concern for computer hardware, network protocol or operating system differences. 

The overall DNET network is defined as the collection of host machines/networks on which the DNET 
software is operating. Each underlying network is considered a DNET "domain". Data 
communications service is provided between any two processes on any two hosts on any of the 
networks (domains) that may be reached via DNET. DNET provides protocol tr ans parent, reliable, 
streaming data transmission between hosts (restricted, initially to DECnet and TCP/IP networks). 
DNET also provides variable length datagram service with optional return receipts. 

Communications and computing services within DNET are provided in an environment based on 
clients and servers. When ’permanent* connections are required, clients request connections to specific 
servers by contacting a ’Master Server* at the destination host. The assignment of specific instances of 
server processes to clients is done by this Master Server as requests are received. The Master Server 
also controls server process creation, prespawning servers as necessary in order to improve response 
times. Local system administrators can regulate the number and type of specific servers. Servers report 
their status to this Master Server so it’s database is always up to date. 

Connectionless datagrams may also be sent between any two DNET processes. The DNET 
connectionless service is implemented separately from the streaming service. 

There are two types of nodes in DNET, Hosts and Gateways. A DNET host is simply any machine 
which can access another machine via DNET. DNET gateways are special cases of DNET hosts which, 
provide protocol conversion "relays" between dissimilar networks in addition to other DNET functions. 

DNET Host software includes a library of basic ’transport level’ I/O functions, DNET application 
clients & servers, a master server (which controls the creation and allocation and permanent circuit 
connection of specific servers on its host) and a Datagram Master Server and Protocol Specific 
Datagram Servers which provide a universal interface to the DNET connectionless datagram service. 
DNET gateways include streaming ’relay* processes. These relays are simply special application 
servers which provide protocol conversion between the underlying networks. The DNET 
connectionless service handles protocol conversion between dissimilar networks as part of its inherent 
design. 

Applications provided with DNET include File Transfer, Remote Login, and Remote Execution. In 
addition, a Network Command Interpreter allows I/O redirection and task ’chaining* across the 
network. Various application level processes may be invoked via this facility. DNET users may also 
add other applications by following interface techniques described in this document. Presentation level 
routines provide XDR data conversion capabilites in order to handle differences in internal data 
representation on different machines. 

DNET also includes a provision for electronic mail and several network utilities of use in both system 
administration and user applications. 

From the user’s perspective, DNET is implemented as a library of program callable functions with 
input, output, and error redirection capabilities. No Kernel Modifications are required on an y machine 
on which the DNET software operates. While this constraint introduces some potential performance 
problems, it greatly simplifies the logistics of implementing and m aintaining a heterogeneous network. 
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While DNET has been designed for initial use by the NASA-GSPC DAVID project, consideration has 
also be given to its future utilization with other applications which must operate in a heterogeneous 
environment. The initial DNET environment is thus limited to TCP/IP, DECNET, and dialup 
communications alternatives and UNIX (ATT System V and BSD) and DEC VMS operating systems. 
Design generality has been maintained as much as possible however, so future inclusion of other 
operating systems and communications facilities, especially ISO/OSI, UNIX/uucp, and IBM 
SNA/LU6.2 and VM/CMS may be contemplated. 


Abstract 
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2. Organization of the Remainder of this Introductory Guide 


The remainder of this guide contains the following information: 

• Discussion of Networking Services Originally requested by NASA 

• Overall Topology of DNET 

• Current Defined Boundaries 

• Definition of Interfaces to DNET 

• Overview of Major DNET Components 

• Implementation 

• Introduction to Documentation Organization 
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3. Services Requested By NASA 


The following is a brief description of the communications 
DAVID project. 


services which NASA required for the 


2 . 

3. 


Task To Task Communications 

1. Initiation of program task at a remote internet (DAVID) node with facility to pass 
arguments/results and propagate termination signal^ 

Transfer and execution of portable programs at an internet (DAVID) node 

Provfck transparent operations which allows 2 programs or command procedures r unning 

on different DAVID nodes on different host environments to communicate with one 
another. 

Operations would include: 

• initiation of remote tasks 

• termination of remote tasks 

• send data & ’interrupt’ messages 

• receive data & ’interrupt’ messages 


File Transfer 

1. File transfer of ASCII and binary files to any internet (DAVID) node with multiple 

authentication options including: r 

• autologin 

• various user/passwords 

2. file transfer between any two internet nodes, neither of which is local to the user 

3. end to end reliability with timeout and acknowledge options 

NOTE: the ability to specify some or all timeout parameters may be dictated by underlying 
protocols and not under control of software DAC is able to provide. 

4. Provides presentation layer function for data conversions so as to make differences in data 
type representation transparent across machines. 

5. Provision for initiation of remote procedure upon successful completion of file transfer 

6. Additional operations 

• check for existence of file 

• delete, rename, append to file 
Remote Login 

1. Supports internet logons (with relay mechanism) 


Services Requested By NASA J 



2. Supports different authentication methods 

• autologin 

• username - password 

3. Supports different terminal types 

4. Provides option to specify execution of user defined logon procedure 
General Utilities 

1. Indication that remote internet node is up 

2. Ability to determine load on remote node 

3. Utility to determine host ids, host names, and host aliases 

Mail 

1. Provide capability to send mail to one or more people or tasks at various internet nodes 
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4. Overall Topology of DNET 


The overall topology of DNET is a collection networks as shown in the following diagram: 


PROCt 



Each of the networks contains one or more nodes (ho6t computers) and some of these nodes 
(gateways) are shared by two or more networks. From the perspective of a DNET user all of the 
networks and nodes appear identical. Positive identification of a specific node requires only that the 
name of the destination node and the network on which it resides be known. No knowledge of the path 
between, nor the environment under which the destination node operates is normally required. This, 
of course, differs radically from the view that DNET implementors and administrators see. The latter 
view involves a collection of incompatible networks and environments that must be combined to bring 
reality to the prior view. In order to provide for such a reality, certain boundaries must be defined as 
described in the next section. 
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5. Defined Boundaries 


The following 'Boundaries' exist for DNET. The boundaries are simply a compact list of the 
environments in which DNET can be expected to operate without an excessive software porting effort 
The current boundaries are: ^ 


1. Communication Protocols 

• TCP/IP (Wollongong, Excelan, and Berkeley Implementations) 

• DECnet 

• BSD Sockets 

2. Operating Systems 

• UNIX (System V.2 and 4.2BSD) 

. VMS 

• MS-DOS (DNET Clients Onlyd) 

3. Hardware 

• AT&T 3B2 

• Sun Model 3 
. DEC VAX 

• IBM PCs (DNET Clients Only, LAN interface only) 

Despite support for a variety of environments and underlying components, the interface to DNET 
users will remain standard. 
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6. Interfaces to DNET 


There are three interfaces defined for the DNET network:: 

• End User 

• Programmer 

• Administrator 

The end user is a person who takes advantage of the networks services through an interactive mode 
involving utilities that arc run from the keyboard These generally manifest themselves as interactive 
distributed services like trivial file transfer protocol, electronic mail, and remote command language. 
The user sees DNET as a homogeneous’ network. All commands to operate applications and the 
behavior of these applications appears to be uniform across all machines on the DNET network. 


The interface provided to the programmer comes in two basic forms: the connection oriented services, 
and the connectionless oriented services. The connection oriented services provide a streaming mode 
of full duplex conversation between two processes. The connectionless mode services provide a 
method of sending and optionally receiving datagrams (packets of information) without previously 
esta bl i sh i ng a connection. Both of these services are implemented through user libraries tW may be 
compiled into the programmer’s applications. The DNET user is provided with extensive 
documentation to facilitate usage of the system. 


The system administrator is provided with utilities for starting and stopping a DNET node, modifying 
the number and types of DNET application servers at the node, altering routing tables and monitoring 
the status of both local and remote DNET nodes. 


For more advanced applications, information is also provided on DNET ’internals’ to allow more 
sophisticated special services to be implemented. This information is provided in the DNET te chnical 
guide and reference. 
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7. DNET Implementation 


The implementation of DNET was designed with low impact on target machine.* as a high priority. 
This low impact philosophy is intended to apply not only to resource consumption on the local 
machine, but also to administrative and user functions. From a resource standpoint, DNET daemon 
processes only require CPU resources when applications request service, and the resources provided by 
the underlying networks are still available to programs that have already been written to interact 
directly with them. All ad min i str ation tasks associated with the underlying networks remain the same, 
and the administrator’s responsibilities are clearly outlined in the administrative guide. The end user 
u t i l iti e s were created with preexisting standards so that retraining is minimized, and the progr amm er 
tools were kept to a minimum, are well documented, and many times operate in a similar fashi on to 
standard file operations. 


The DNET de si g n also takes into account the importance of simplicity in acting new a pplication* in a 
heterogeneous environment. DNET specifics a minimal set of rules for writing client-server pairs to 
implement new applications. Details are provided in the DNET Programmer’s Guide and Reference. 
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8. Major DNET Components 


A small collection of DNET components arc required on each node on the DNET network: 

DNET Master Server 

This server provides a ’well known’ port for the connection oriented DNET services. 
All server applications (see Programmer’s Guide) are started and maintained by the 
master server. One master server is required per protocol per node. Thus, a DNET 
node which is connected to both DECnet anda TCP/IP will have a Master Server 
’listening’ on each of these two networks. 

DNET DataGram Master Server (DGMS) 

The DNET DGMS is the heart of the connectionless service and provides all routing 
and switching services for datagrams either coming in from a network, or from it’s 
genesis in a user process. 

per protocol DataGram Server (DGS) 

This component provides the low level interaction with a particular underlying 
provider (ie TCP/IP). One such server is required for each protocol at a par ticular 
DNET node. All DGS components then provide a standard interface to interact with 
the DGMS component so that all networks appear to have the same interface. 
Beyond that, the DGS components are merely dumb relays. 

Relay processes 

These processes provide relay service for the connection oriented service and are 
only found on gateway machines. The relay processes actually write out on the 
proper network in loopback mode to get to the master server controlling that 
network type. 

Application Processes 

These processes provide the ’standard’ collection of DNET applications for the user. 
Administrative Processes 

These are a small collection of scripts and rules which allow the local system 
administrator to control the local DNET functions. 

User library 


Reuser library contains all of the routines necessary for a progr amm er to use the 
DNET services. A separate set of rou tin es are provided for connection and 
connectionless oriented services. 
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9. Organization of the DNET Documentation 


The DNET documentation is organized around the three interfaces (user, programmer, administrator) 
defined above. These documents together with this Introduction Guide and a Technical Guide 
describing the internal implementation details, provide a complete description of DNET. There are 
thus documentation categories for end users, programmers, network administrators, and inter nal 
programmers. Each of the above mentioned categories is divided into two manual*, a guide and a 
reference. Providing two manuals per category allows the documentation to act as both a quick 
reference for users who need only specific details, and as a learning or refresher guide. Utilities are 
provided so that the reference manuals may actually be stored on-line if space allows so that a DNET 
user may interactively reference the manual from their terminal. Additional Notes are provided for 
each category, as appropriate. 
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1 . DNET Overview 


This section provides an introduction, from the user’s perspective, to the DNET Network for 

SfdSb^ a f C r mUDiCad0nS ' ThC Vari ° US fimctional dements which make up DNET 

are described as are some of the important assumptions made in the design 

1.1 What is DNET? 


tat^nr e er a ed OT hT UniCati ° nS envir( T ient which Provides a consistent view of a number of 

SeC- 7^^^ NetWOrkS * P resent which use the 

f communication protocols. DNET provides a ’seamless’ or uniform interface to 
ese networks and machines, giving the impression that a single homogeneous network is being used. 

a consistcnl T>ar«port’ Level interface to the underlying existing 
networks/protocols on which in operates. Various applications may use these transport hdlities fof 
their communication needs. DNET includes a set of £mmonly used ’gene^ apS^Ta baS 
working set of tools and as examples of how this communication facility may be used. 


NOTE. DNET (currently) operates as an application on machines on which it is available While this 
S'T'T strategy introduces some potential perform.*, problems, i, greati^pIfliT^S 

ogulwa] problems in operating a heterogeneous network. Further rationale for this approach is 
provided m the DNET Technical Guide. approacn is 



1.2 Miyor Elements of a DNET Network 

A DNET network consists of the following major elements: 

1 (wi,h ~ ™ * dnct - 
2. DNET Hosts - machines which are able to communicate using DNET services 
3 ' DNEI H ““ - f — coo version berween ,he 


1.2.1 Network Arrangement 
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DNET can establish a "permanent virtual circuit-. In this mode an -open" function is called to establish 

CStabL ^ cd com P rises «% processes and network connections dedicated 
e»d^vely to the stream mode transport of date between the end points of the circuit. Permanent 

rCdUCC j h l nUmber f of network connections that must be established and the associated 
a "str^W ^ &lgmflCan U y unprovC8 network Performance. When date is transmitted in 

the i ”“«“ -ore than ofets the imtinl cos. of 

Pr / OVideS ! ength data « ram The user interface to this service is 

Date^m? 658 t C ' “a OP€ u" “ rCqUircd bcforc Slartin « Process to process communications) 
Datagrams may be used to either transmit date or signal information. 


1.12 Existing Networks 

Thcundc'l yingnctworb «soda,e< I wW, , DNET are ore* .bid. Irere existing reliable, data stteanting 
pabditics. The networks in which DNET may currently operate are TCP/IP, DECneL and 

Asynchronous links. DNET depends on the transport services of tfae these ’underfyutf networks “d 
presumes that they are operational. w networks and 


123 DNET Hosts 

DNCT Hosts are computers at which local processes may use the facilities of DNET to interact with 
emote process^ in the heterogeneous network. Any computer connected to one of the networks 
served by DNET may become a node on DNET provided the following conditions apply. The machin^ 

L DNCT dCnt °“ 3 SPedf,C CX1Stin8 “ CtWOrk (e * TCP/IP Net ** SPANET > c‘c.) which is known to 

2. have at least one DNET master server listening on a known DNET network. This requires the 
following processes: The DNET PVC Master Servers^) DMSDEC and/or DMSTCP and the 
DGSDEC MaStCr Server ( s )' DGMS 811(1 Datagram Protocol-specific servers: DGSUDP and/or 

3 Z&T ° nC DNET aPpUCati ° n S£rVCr runnin 8 (* requests from remote nodes are to be 


1.2.4 Gateways 

ar ‘ nod ? “ DNET "*** « connected to one or more networks in which DNET is 
P ^ i/ at ^ g ‘. The functlM1 gateway is to bridge the protocol and other differences between these 
networks in a transparent manner. The gateway functions are implemented in special DMET PVC 
Relay servers and Datagram Servers which provide protocol conversion for Permanent Virtual Circuits 
^ connecbonkss datagrams respectively. Except for their special-purpose function, these servers are 
handled just like any other DNET application servers. ^ mese servers are 


1.2.5 DNET Routing 

DNET employs hierarchecal routing. Each DNET node contains a routing table which indicates, for 
each network known to DNET the next host to contact in which to Z £££ 

1 a ^ UlC DCXt hops b **“ tab,c are 8,1 DNET gateway machines, Tile user 
g nerally need not be concerned with the routing tables, however a ’map’ of the DNET network or at 



least the names of remote DNET nodes and networks of interc* j, eMci* h . rfwlBr f ^ N „„ 

1«3 What the DNET User Has Available 

1.3.1 Applications 


TwSSfJ' Xi£lto^SSt7x lp^ a 

applications will be at the discretion of the a dministrate. *t >k- . The rtNFT 

-» <» ' — ' » *— -SS^^?.^5L*SS 

The available applications include: 

1. FUe Transfer - Ioosedly based on TFTP with some enhanced features 

2 ' fnTmrf ^ *° ’***’ ° r host ’ * aUows fuU interactive sessions with UNIX servers 
and more limited sessions with VMS servers 

3 ‘ ^S M ^ tW c rk P°? m r d I f terpreter * A 8 en eralized remote execution and task redirection 
application - Similar to the redirection capability of UNIX 

4. Mail - a basic system similar to a stripped-down UNIX mail 

5. DNET Status - a generalized network status utility similar to ’nctstat’ 


1.3.2 Presentation Level Services 


DNET provides a limited Presentation Level Service for 
deflnined applications) This service allows: 


use by the above applications (and 


user 


Conversion of Data Elements between dissimil ar marking 
Representation) functions. 


via the SUN XDR (External Data 


1.3.3 Basic I/O C Function Library 


en^onment I /rPfi m ? y *** usc< * to generate custom operations in the DNET 

“S^NKT^, 7 P 7”? de COmmunkations facilities between tasks on different hosts 

™^DNET. The* faeddm, delude pen.™* virtmd circuits, commctitmless datagr ams,lS 


The I/O library may be used in two ways: 

1 . Law Level Connectionless Ifcsk-to-lfcsk Communications - using the Datagram and Shmallina 
elsThere kDNCT ” *** 1/0 packagC ’ ^ USCr may communicate with other processes 

2. User Specific Custom Applications - by following the conventions for DNET Client-Server 

the lCTd c “°” •"■***« «*“ «■ 1— i » 

PJuther discussion of the bank I/O package is fouod in the DNET Programmer's Guide a*! Reference 
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2. How to become a DNET User 


1. Tile machine which you are using must be ’known’ to DNET and have DNET running locally. 

1 SLdt I ap^p SilTtS ££ T " 10 “ CO '“- ™‘ <» be 

1. UNIX 


.profile 


set dnethome and PATH to -/dnet/bin 


2. VAX/VMS 

The dnethome directory must contain the following machine specific file; 

DAC Microvax II 
dnJogin.dv 


NASA-GSFC - DFTN1C VAX 
dnlogin.dft 

The file 


loginxom 


m the user's login directory must have the following lines. The example given is for the 
machine dependent. ^ ^ dcfuutlon for dnet - hoin<! “ d <l»login.XXX will be 


$! DNET Specific Environment 
$ set proc/priv = gr pnam 

$ define/group dnet home $dlskl:[sys0.dnetdnetl 
$! run DNET login script 
$ @dnet_home:dnlogIn,dv 


£ d jz * - — - *~ 

1 •" “* b«< oa^ea for Uae n^a) ^ ^ y0 „ ^ „ 

4 ' JZ2*S!SZS££Z DNCT ^ yoa aecd par. Thcac arc 


3. An Introduction to DNET Applications 

This section provides a brief introduction to the use of tvnical dnft ^ 

apphcations have been designed and implemented with twopSpo^f a PP^ons. The several 

L tamcditol, useful in solvit, typfcd p**^ ere „ ^ ^ 

2. To serve as examples of how to use the DNET tools to build other apphcations. 

*■ '* •"*» *««' tie DNET network. I. 

Client-command Destination-network Destination-host 

" ad T °" D ? E T “ d '**“ *° *=*>"» a nie transfer 
basic (trivial) file transfer ap^taion. ' “”"“ d » the DNET 

dtftp spanet iaf 

Other apphcations are invoked via a similar syntax. 

3.1 The Echo Routine 

f 0 * 10 routine, decho, provides a convenient introduction to the use of DNFT 



< ffihocd Clurtw 

decho is invoked by entering the following command line: 
decho dest network desthost [CRJ 
A message will be printed on the terminal: 

Attempting to connect to dest network dest host 

InirW seconds, the connection to the destination should occur, deck, should the. respond with 
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Ready 


or: 


dechod server unavailable at destination (DNET error nnj 

Assuming the ’Ready 1 prompt appears, one may then type an arbitrary line of text, e.g. : 
12345 (CRJ 


After a short delay, this text should appear on the screen a second time as it is echoed from the remote 
server This process may be continued indefinitely. The ’echo’ delay provides an instantaneous, 
subjective indicator of the performance of DNET. Keep in mind that this delay is heavily dependent on 
the load on intermediate DNET nodes which may be performing protocol relay operations. 


When finished using decho enter the following, machine dependent terminator 
system. 


to exit to the operatin g 


UNDC: 

CntrlD 


VAX/VMS: 

Cntrl Z 



4. Help Facilities 


P"? ar *^° S ° urccs of ^>P f" DNET applications, manual pages in the DNET User's Reference 

^t^ d S umentadon ’ °- B - versions »« - S22 STS 


4.1 Manual Pages 


Manual pages in the User's Reference follow the style of UNIX manuals, 
examples in this Reference. 


The user is referred to 


4.2 On-line Help 


DNET provides an online 'manual' facility which may be of help to the user. 

The manual pages found in the various DNET Reference Manuals are available on-line as follows: 

4.11 UNIX 

The DNET manual may be invoked by entering: 

d m an dnet_fu notion name 

wbere^(lto_toctoi_iiaiiie U 0* DNET tocto, or applicator for .Uch addition inf to. is 

4.12 VMS 

On-line Help for VMS has not been implemented in this release 
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5. File Transfer 


5.1 DNET TFTP - DNET TVivial File TVansfer Protocol 

•*« ' P rocess ' n ft to, 

^ * “»»to of fcafu*, buyoud 

d«p alao atomic a username a*f paaawd ,„ b. eu,.,ed to order ,„ eruu^to ,„ 0* r.n.«e a^ern. 

5 * 2 Invoking DNET File TVansfer 

5.2.1 DTFTP from the Command L in e 

The DNET file transfer facility is invoked at the command line by entering: 
dtftp [dnet network] [dnet host] [CR] 

This will cause the file transfer prompt to be displayed: 

dtftp > 


If the destination was not specified on the command line, 
desired by entering the command- 


a connection may now be attempted, if 


connect 


The connect request will require the network and host information. You will be queried for: 

Network: 

and the 

Hoot* 

Then the following message will appear 
Attempting to connect to [network] [host] 

Once a connection has been established with the remote host vou will he nrnm^df , 

at that machine: nos *’ ^° u ™ ^ prompted for a login account 

Login: 

Enter a valid account name for the destination host. 

You will then be prompted for a password associated with this account: 



Password: 

Enter the password for the account name just entered. 

When the account information has been verified, the client will respond with the message: 
CONNECTED 

You may now proceed with other commands as below: 


S3 User Commands 


Thejollowing commands arc provided with dtftp. These commands are self-explanatory except as 

cd XXX - change the default directory on the remote host to XXX 

get name [newname *] - retrieve a file from the remote to the local host 

help - display help message for available dtftp commands 

led XXX - change the default directory on the local host to XXX 

Ipwd - list the current directory on the local host 

Is - list the contents of the current directory on the remote host 

11s - list the contents of the current directory on the local host 

! c <w“>»and string - Allows execution of a local command 

mode - Allows specification of binary or ASCII mode 

put name [newname •] - transmit a file from the local to the remote host 

pwd - list the current directory on the remote host 

quit • end the file transfer session 


• - In get or put operations. If newname is not given, it 
Is assumed that name is the target file. 

If the target file already exists, a warning message is presented: 

Destination File Exists - Overwrite (y/n)? 

Ifyou answer yes (y), the old file will be overwritten. (In VMS, this 

will not actually occur as a new file extension will be assigned to the 

target file, however the warning message is consistent for both UNIX 
and VMS). 
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5.4 File Transfer Errors 

Error reporting from DTFTP includes the following: 

1. Login incorrect 

2. File Not Found 

3. File I/O Error 

4. File Access Violations 


Except for the obvious question of 
failures’ are self explanatory. 


access privileges associated with login failure, 


most non-fatal 


5*5 A File Transfer Example 

As an example of the use of dtftp, consider the following diagram: 


C ourt , G*» 
Pat, ttc. 



pro^oLS? ^Si^commtds^ to * “ * c 


$ dtftp spanet daevax 

attempting to connect to spanet daevax 

Login: dnet 

Password; **• **« 

CONNECTED 
dtftp > put hackl hack2 
completed ascii pat of hackl to 
dtftp > quit 
$ 





5.6 Using the Network Command Language for File TVansfer 

Rle TVansfer may also be accomplished using the DNET Network rnmm»v( i . 

There are advantages and disadvantages to using the Nn for ni r — Laoguagc (NCL). 
U* Network cJLkI La,^ S' ‘JSSiS^ ^ 0p,,0 “ “ ” 
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6.1 Introduction 


6. Remote Login 


^.°^ tr'^.‘ l '' ltC * d0 ' i al1 ? d» rarer to log <Wo arf em^, «, a. mteraoire ^ whh 
V“2“ - ? **• °f e ““•‘•“o Ires been made to the remote host, the user will aooeer to be 

djjectl y coQneq ed to rha. he. Only msbmtaoeou. oetw* perfotmtmreiold rfeette *SZ o d^ 
work, mclrrfo* | soeen onented editing. Thun dlogi. it simile, to the telnet, rlogm, or «,Z „ 
facilities with which the user may already be famili ar 

A schematic of the DNET remote login is shown in the diagram below; 



STS taTS e „‘S„” a ? * TT k0m ? ither UNK « VMS hosls, however the remote 

interactive VMS DCLVhrfr ^^1^' mmpkte “ >K ' aa ' ve operadons to take place. (An 
leracuvc VMh DCL shell has not been implemented to date under DNET). V 


6.2 Invoking DNET Remote Login 

The DNET remote login facility is invoked at the command line by entering: 

dlogin [dnet network] [dnet host] [CR] 


Once a datastream has been opened to the destination, you will be prompted for account information: 

login: xxa 
Password: ******* 


If this information is determined to be correct by the remote machine you will placed in your ’home’ 

tST* ZT prcferrcd ,shc11, “ cxccutcd - You ma y now perform any fnte^ctfve o^erad^ 
winch you might do were you directly connected to the remote system. operations 





63 Ending the Remote Login Session 




6.4 Security Issues 

6.4.1 UNIX 

CO Ibe sjutem. This rile is consulted by the 

64.2 VMS 


VAXeS -c‘ he “ h “ d -^ f « VMS 

before DNET is used in a pToduSou enmonTent " ^ “« <* “™acd 
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7.1 Overview 


7. Network Command Language 


The DNET Network Command Processor is a cnmman j . 

heterogeneous multi-network cnvironment^This DNET^fa^itvnll ^ n ® ua ® c !■«*** for use in a 
across the heterogeneous network and Drrwi<i-c f rtr a* Wl 7 ® enera * contro * of processes 

and/or processes located at arbitrary DNET Hosts. ' ° D ° f “ put / out P ut streams between files 

Three Software Elements are required for the Network Command Processor. 

“ode, to interpret the Network 

command to next net/host/process in Ihe command^ *“*** SpaWmnft 3nd ‘ eod remaind er of 

" C ° DUnaild ^ fr °” NCI or another NCS; 

to next net/host/process in the command ^ 0 ° t 'T™*™ ° f Command 
registered in the PVC Master server tables. ^ DNET a PP hcaUo “ server and is thus 

" «Ud. may be spawned by tbe 

7.2 Network Command Processor Schematic 

U,eS ' — " %ne below. Tbe 

Netl::Hostl:FIIe X > NeCnHasttl^fp^,.^.*, > NM3::H„,U ; Pr„c3 > N,M=:Ho».4:Flle Y 


DNET Host 1 
(<» Nat 1) 


DNET Host 2 
(o* Net 2) 


DNET Host 3 
(on Net 3) 


DNET Host 4 
(oo Net 4) 



73 Network Command Language 





















7*3,1 Command Language Syntax 


There are two types of objects used on the command line - Files and Tasks. Output can be directed to 

r . a w “other task. The command language makes a distinction between files and lacW 
(executables) by preceding tasks with an ^ “ ““ tasks 

Filename syntax is: network_iuune::bost munerfUename 

Taskname syntax is: network name::host aame:ta8knajne(panunl, param2 _) 

0nly ° ne netWOrk COmmand ]an ^ c °P* T * or s> •>•■ The •>■ indicates redirection of 

An example command is: 

starnet-rxhoskcfile > yhost:*sort > myflle 

“J ““ fifc 1 " imed fr0 " koa HkW 10 the host 'yhost*. o. host 

**? ‘® e . wdl J* “"a 1 -ykosf resident sort tttiiity. The resulting output will then be 

saved in the file "myfile” on the local system. P 

Other examples are given below. 

°‘ mC “ SpedfiWi l ° Cal “ “ 5 "“ e<L *!■» ground the 


7*3*2 Using The Command Language 

^ma^ nameS 3PPear “ C ° mmand the y “Pty *be execution of file i/o servers. The network 


dacji€t:n«x2;dav{d comm > g_net::hostl:*cbeckp > results 

requests that the contents of a file "david.comm" on host "vax2" in the network "dac net’ be input to the 

°^ h< f r “ the ° etwork "* ** o^P* be placed m the fde ’Lulls’ in 
tlie host on which this network command is being executed* 


The network command: 

Mt_onexvax6:c-flle > hostla-cflle 

requests that the contents of a file "c-file" on host "vax6" in the 
’s-efile" 


network "net one" be copied to the file 


7.4 Network Command Interpreter 

ThcNetwork Command Iwerprere, (or clien.) is invoked as an applic*ioo fron <he shed promp. on 
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%) dud 


dnd> command string! 
response to CS1 
dnd> command st ring ! 
response 


etc— 


7.4.1 Status Reporting ( from last Network Command Server) 

^cn the command line specified by dnd has been executed, an acknowledgement is propagated to 
the initiating client process as shown in the following diagram: ^ 



7.5 Initiation of File Transfer from One Remote Node to Another 

The Network Command Language may be used at a third party location to initiate file transfer A 
typical command would be: 

dncl> netl(h:host3:filexx > c-net::fliost:newfi]e 
or 

dnd> mynefcUiostfc*dtftp filename options > newfile 
Where filename and options are parameters to the file transfer task *dtftp”. 

The effect of such a command is shown in the following diagram: 
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8. Remote Execution 


8.1 Passing Arguments to Tasks 


fr T * CalUng t3sk t0 Network Command Processor is by command string, as 
intSa^ “ preCeduig SeCtlOD ' This is used in both the terminal interactive and the "CU^age 


8.2 TVansfer & Execution of Portable Programs at a Remote Host 

commaiKls^ CXeCUti ° n * ““8 thc “ctwork command processor. For example the 

dnd> net3::host5:filez > net3::host2rworkflle 

dncl> net3::host2:*workflle 
will transfer and execute a file. 


8 J Initiation of Remote Procedure Upon Completion of File TVansfer 

ft is also possible to use the DNET Network Command Language to perform a file transfer followed 
by the execution of a remote procedure. Several alternatives are possible. 

1. Two separate commands: 

transfer the file 


dncl> bnet::host3:file4 > c-nebudiostmewfUe 

followed by 

execute the remote procedure 
dud > c-net;:xli os t; ♦format newflle 

2 . 

One ’composite 9 command: 

dnd> bnet::host3:file4 > c-nefcrxhosLnewfUe > c-net:uh os t: •format 



9. Electronic Mail 


DNET ^ EIectronic MaU Polity- This facility allows mail 


9.1 Mail Operation 


The general operation of DNET mail is shown in the following diagram: 


FUe TVaaiitr to Mail Server 


S«nd or Read Mail 



9.1.1 Sending Mail 

DNET mail is invoked using syntax similar to that of other DNET applications 
dmall network host user 

where network = DNET network 

host s hostname on that network 

user Is presumed to be a valid user on the destination machine 

The sender then responds to the following prompts 

To: Kceiver_login_name_atjiestination 

From: Senders name ~ 

Subject: wm 
Ccxxxxx 

Please enter short message and end with three CRs 

this is a test 

CR 

CR 

CR 


to be sent from the local 
received from other hosts 


as indicated below. 


The following prompts will then appear as the message is sent 
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CONNECTING 

Completed ascii put of mail to destination 

9.1.2 Reading Mail 

To check for eoy DNET mail which may have arrived at your loonim, amply erne, foe command 

dmail 

and request the Read Mail Option. 


9.1.3 Auto Notification of Mail Arrival 

DNCT Mail includes a provision for automatic notification of mail arrival each time a user loss in If 

mail is present for your account, the message: c*cn umc a user logs m. If 

You have DNET mail ^ 
will be presented as part of your login process. 

NOTE; in order for this feature to be activated, the appropriate DNET loidn scrim must h, ~r 
° r lOg * aX0m n,e - ™ i "k must ““S* ^ ’checkdmair to be executed m part 


10. General Network Utilities - dnetstat 

— » *— *. a van.,, 

local and remote nodes^SeL ' Wormatron wbch dnetstat can obtain for both 

1. Is DNET ’alive’ at the Node? 

3. Statistics of DNET Use at the Node 

4. DNET Routing Tables at the Node 

The general form of the dnetstat command is as follows: 
dnetstat [dnet network] [dnet host] [options] 

If the network and host arguments are both omitted, the local host is assumed by default. 

£: s : assf - DNEr “ two, ‘ ■ -**-*■ -* ■ *■ *->- «. 


10.1 Testing if DNET is alive 

Aa an imroducton do.™*, liy using the 'pug* option on your local ho6t. This is done by typing 

dnetstat -p 


If DNET is ’running’ on the local machine, the following message will appear: 
DNET is ALIVE at dnet_network dnet host***** 

This response indicates that 

1. At least one DNET PVC Master Server is running on the local node 

2. The DNET Datagram Master Server is running on the local node 

If DNET is not running normally on your system, the following message will appear 

Timed out waiting for response 


Now try using dnetstat to ’ping* another DNET host on the local or a distant DNET network. 

SSS r arC fUrthCr a ? sured DOt ^ ^ DNET software running at that host, but 

also that the DNET datagram semce is operating (at least between your machiTS theSmThosi)! 


10*2 Obtaining Status of DNET Servers 

dnetstat may be used to obtain the status of DNET processes at local and remote DNET nodes. 
This information may be obtained in the following formats 

1. Connection Oriented Services only 

2. Connectionless (Datagram) Services only 
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3. Both Services 

4. Short Display Format - types, number avail, and state of servers 

5. Long Format - short format info + (Process IDs) and Start/Idle Times 
The default format is 


Both Services 
Short Display 


The short listing of server status is shown below. The command used is: 

dnetstat [network] [host] 

******* DNET VIRTUAL CIRCUIT SERVER STATUS at: dnettl sun3- 
SnrT>pe Image PS Av Max S# 

dmstcp 
dechod 
drexccd 
dtftpd 
dndd 
dlogind 


dechod 

drexecd 

dtftpd 

dndd 

dlogind 


1 

1 

1 

3 

1 


1 

1 

1 

3 

1 


1 

1 

1 

3 

1 


1 

1 

1 

3 

1 


******* DNCT CONNECTIONLESS (Datagram) STATUS at: dft tl sun3* 
ProcName S StartTime 


dgstcp 1 

1 

dnstatd 1 

dnetstat 1 


Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:46 


A longer listing of the server status may be obtained using the I (long) and c (connection) options. 

dnetstat [network] [host] -led 


DNET VIRTUAL CIRCUIT SERVER STATUS at: dnettl sun3- 
Srv Type Image PS Av Max 


S# 


PID IU 


dmstcp 

dechod 

dechod 

i 

drexecd 

drexecd 

i 

dtftpd 

dtftpd 

i 

dndd 

dndd 

3 

dlogind 

dlogind 

1 





5489 


1 

1 

1 

5491 

N 

1 

1 

1 

5492 

N 

1 

1 

1 

5493 

N 

3 

3 

3 

5494 

N 




5497 

N 




5498 

N 

1 

1 

1 

5499 

N 


St Time 
Aug 1 10:44 


Idle Since 


Aug 1 1C 
Aug 1 10 
Aug 1 IQ 
Aug 1 10 
Aug 1 10 
Aug 1 10 
Aug 1 10 


A long listing of the both virtual circuit and datagram server status may be obtained using the I (long). 


e“i a JL? JLZ -L! *• 


c (connection), and d (datagram) options. 

dnetsUt [network] [host] -led 


******* DNET VIRTUAL CIRCUIT SERVER STATUS 
Srviype Image PS Ar Mu 


•t: dnettl sun3: 
S# PID 


IU 


dmstep 

dechod 

drexecd 

dtftpd 

dncld 


dloglnd 


dechod 

drexecd 

dtftpd 

dncld 


dloglnd 


1 1 

1 1 

1 1 

3 3 


1 1 


1 1 

1 1 

1 1 

3 3 


1 1 


5489 

5491 N 

5492 N 

5493 N 

5494 N 

5497 N 

5498 N 

5499 N 


St Time 


Aug 1 10:44 


' DNET CONNECTIONLESS (Datagram) STATUS 
ProcN “ ne S PID IPC-Name 


at: dnettl sun3: 
IPCID SIG 


MSzStartTlme 


dgstep 1 

1 

dnstatd 1 

dnetstat 1 


5482 

DN 5482 

1 

5481 

DN 5481 

2 

5495 

DN 5495 

3 

5504 

DN 5504 

4 


0 OAug 1 10:44 

0 OAug 1 10:44 

0 OAug 1 10:44 

0 OAug 1 10:45 


To obtain the routing table at a particular host, enter the following command: 
dnetstat [network] [host] -r 


An example of output resulting from this command is: 


******* DNET ROUTING TABLE at: dnettl sun3: 

DestNet Nxt Host NxtProc DG Protocol 


dnettl 

spanet 

starnet 


NULL 

NULL 

tep 

daevax 

drelaytd 

tep 

daevax 

drelaytd 

tep 


Idle Since 


Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:44 
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1 1 . Presentation Services 

DNET provides a limited presentation layer facility. 

WitWn the DAVID environment, the single most important coding problem across heterogeneous 
machmes is the internal representation of data. Information moved from one machine to antJher may 
only be viewed consistently if data types are faithfully ’mapped* between machines. X 

i “ tegCrS “ 32 ** < * uantitics «» ^presents floating point 
wth 64 bits while the receiver represents these two data types as 64 and 48 bit qualities, 
respectively, serious misalignment of data flies will occur. 

The Presentation Layer Service provided by DNET is a subset of the SUN (XDR) External Data 
Representation and/or Existing Data conversion facili t i es of DAVID. 


11.1 XDR Services 


XDR Services are currently not available at the user level in DNET. For further information 
XDR at the programming level, the reader is referred to the DNET Programmer’s Reference 


on use of 
Manual. 



12. Glossary 


The following terms are used in the description of DNET: 


Applications Servers* 


Servers such as Fde Transfer, Remote Login, Remote Execution, etc that perform 
semces for clients. Applications Servers are invoked on demand by clients after using 
the Service Assignment to obtain the name of an available server 


Connection Lock Ihble- 


Ust of open connections held by process for use by its Basic Datagram I/O package. 
Locked connections result from user requests for Permanent Virtual Circuits. 


Datagram Master Server (DGMS)- 


* ESTT 1 81 each DNET host and gatewy, which pcovxic „ blcrfacc 

SiSa ^ “™ rS thC DNET Daugra. m d signalling 


Datagram Protocol Servers (DPS)- 


Master Server Init Ihble- 


^otocolspedfic servers located at each DNET host and gateway, which provides an 
DNET Connectionless an interface to the underlying network Datagram service. 


^ 8 T P ‘Ws.insinitdec matai * initialization information for 
the DNET Master Servers including the type of server to be activated, the maximum # 
aUowed at this host, and the number to make available initially, and an indication of 
whether the server must be prespawned. The tables are updated by the local System 
Administrator at the specific DNET host. y 


Master Server Ifcble- 


f ° r h ° St ’. U u contai,ls information on the types and numbers of each 

class of DNET server actively supported on this node at any instant. Each generic 
server entry points to a Server Instance IfcMe which lists the current specific instances 

° f SCrVCr 11 * thc Master Server and by specific 

DNET application servers. 


Master Server Process (DMS)- 

Processes, one per Network, managing the Master Server Table, handling serve,, 
registration, server assignment, and server control They are spawned by network 
start* up command flies. ^ 

DNET Basic I/O package* 

Included as library within an application program, it provides network i/o interface 
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Gateway- 


including datagram formattin g 


A DNET node at which communicaton protocol boundary is passed. DNET relay 
servers move data from one network to another performing an effective protocol 
conversion for streaming services. These servers are created, allocated, and used like 
any other DNET streaming applications servers. The Datagram Master Server, in 
conjunction with protocol specific datagram servers performs a similar function for 
DNET datagrams. 

Network Command Line Interpreter- 


DNET Client process that directs the execution of network commands using 
datagrams sent to various hosts and several servers. 

myname - hostname table- 

A table, tblsjnyname, maintained in the dnet_home directory on each DNET node 
lists the DNET networks to which that host is connected and the name(s) by which the 
local host is known on those networks. 


Network Command Language Processor- 

Server that directs the execution of network commands using datagrams sent to various 
hosts and several servers. It is an application server, copies can be pre-spa wned or 
spawned on demand. 

Network Command Server- 

Spawned by request from Command Language Processor, this Server is directed by 
Command Language Processor. It spawns processes and directs i/o to execute network 
commands. 

Network Status Server- 

Resides in each network host. Receives Host Status Tables, Host Alias Table, Well 
Known Server Tables, Connectivity Tables, and periodically sends "I am alive" 
messages to the Administrative host. To ensure these periodic messages are sent the 
Basic datagram I/O package uses a timer/wake-up signal to initiate the transmission 
of the message to the Network Status Client. Because this is done by the I/O package 
and there is a copy of this package in every process that uses network I/O the network 
status data is collected on a per process not per host 

PVC Relay 

A DNET relay used in the completion of DNET Permanent Virtual Circuits (PVCs). 

Relay 


Special DNET application processes located in a DNET gateway which perform 
protocol conversion for DNET strea m i n g service between dissimilar networks The 
appropriate Master Server process ’listens’ on a particular protocol boundary when 
idle and assigns a relay when a request for a protocol h’hop’ is received from DNET.. 
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The relays are named according to the protocol boundary which they are intended to 
bridge. Thus a T-D relay services requests which arrive on a TCP/IP network, 
relaying data to a DECnet net. Relays operate in a fill] duplex mode while act uall y in 
use. 


Router 


DNET employs a hierarc h ical routing strategy. Each DNET node has, for every 
(DNET) network known to it, information on the next DNET host to contact in order 
to move data toward the des tinati on. The DNET router function uses rh^ information 
in the routing table as follows: Given a destination network, host, and process, returns 
the next ’best’ hop (network, host, process) to ’move’ toward the destin ation 


Routing Tfcble- 


A hierarchical routing table that contains the next ’hop’ from the local DNET 
host/network in the direction of all other DNET networks. A minimal version of this 
table is provided with the distribution copy of DNET. The table is currently 
maintained manually by the local system administrator. In the future, this table will be 
dynamically configured and maintained by the local DNET Network Status Server 
after in rial startup has taken place. The routing table is named tbls.net and is located 
in the dnet_home directory. 

Server Assignment Function- 

Returns the name of an available server to a requesting Router, and updates the 
Domain Server Table. 

Server Instance Thble(s- 

Lists the current specific instances of a particular class of DNET Application Server. 
Entries are made by the Master Server and cleared via dn doneQ calk from the 
servers as they complete their tasks. 

Server Registration Function* 

This function is part of the Domain Server Process. It updates the Domain Server 
table with information from Servers (e.g."now in use"). 
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DNET 


USER' S REFERENCE 


Version: 1.16 

Print Date: 08/10/89 12:28:00 
Module Name: user.ref 


Digital Analysis Corporation 
1889 Preston White Drive 
Reston, Virginia 22091 
(703) 476-5900 


Thii SBIR data ic furnished with SB1R right* under NASA Contract NASS- wist p__ * . , 

■he Gowmmem agree, IO uae thu data for Government pu^oe* only ^t Lll M be °* *“ “*T ,ob * deli, * re < 1 “»*er thia contract 

puipoaea) during iuch period without permiaaion of the Contractor em* that oaed outride the Government (including dieckmire tor procurement 

* «W<* oontracton. Alter the JL* %££££*£ f T"* *“ *>*> — T be docked ,c 

pmpt-ea, bu, i, relieved from .U d*ioriire protub, „ona and ariumeaTlLhty tor 00 

affixed to any reproductions erf this data, in whole, or in part.* 7 nonzed uaed of thii data by third parties. This Notice shall 


Copyright 1989, Digital Analysis Corporation 
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DECHO(l) 


DNET 


DECHO(l) 


NAME 


decho - dnet ’echo’ client 
SYNOPSIS 


decho dnetjietwork dnet host 

DESCRIPTION 


The decho command performs a simple demonstration and test of the DNET network A 
DNET permanent virtual (streaming) connection is opened to the destination network-host 

carHage'return ^ " h ° St “ the “ ech ° ed back from the destination after each 


The command provides a convenient 
performance of the DNET streaming 


means of demonstrating the setup time and end-to-end 
service. 


The ability to run decho depends on its presence in the Master 
destination host. 


Server Init Table for the 


Command line arguments 

dnetjietwork name of the destination DNET network 

dnet host name of the destination DNET host 
SEE ALSO 

dechod(l) 

DIAGNOSTICS 

The message "Ready” will appear after decho has succesfully connected to the snecified remote 
node. An error message will appear if a connection can not be established. 



DLOGIN(l) 


DNET 


DLOGIN(l) 


NAME 


dlogin - dnet ’remote login’ client 
SYNOPSIS 

dlogin dnetnetwork dnethost 
DESCRIPTION 

oltT r, r hf e d D !* T n " work - A DNET 

standard DNET command line prompt for remote login is Then pretmed " ero0rk:hoS, ' A 

DSH > 

Je'TiSoTm.S“' ,e C ° mmmiS WhiCh ““ bS md ™°° d “ environment of the 


xxxxxx 


The dlogin command provides 
instructions on a remote machine. 


a convenient means of 


executing simple command line 


The ability to run dlogin depends 
destination host. 


on its presence in the Master 


Server Init Table for the 


Command line arguments 

dnet_network name of the destination DNET network 
dnet_host name of the destination DNET host 

SEE ALSO 

dms, dlogind(l) 

RETURN VALUE 

ERRORS 

The call fails if: 

[DDGTB] 


DMAIL(l) 


DNET 


DMAIL(l) 


NAME 

dmail - dnet ’mail’ client 
SYNOPSIS 

dmail dnet_network dnethost dnet_user 
DESCRIPTION 

The dmail command performs a simple mail transfer to another DNET user. 
dMtinationhost rUn dmaU depends 0n its P resence in th e Master Server Init Table for the 

Command line arguments 

dnet network name of the destination DNET network 
dnet_host name of the destination DNET host 
dnet_user user at the destination DNET host 

SEE ALSO 

dms, dmaild(l) 

RETURN VALUE 

ERRORS 

The call fails if: 

[DDGTB] 
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DNET 


DNCL(l) 


NAME 


dncl - dnet ’network command language’ client 
SYNOPSIS 
dncl 

DESCRIPTION 

The dncl command invokes the interactive dnet network command language program This 
program allows for processing of a single data stream in a distributed environment. To do this 
the processing of the data stream is broken into sub command lines SCL (which together make 
up the dncl command line CL). The dncl CL may be entered after the dncl prompt: 

dncl> 

The following is a synopsis of the dncl command line: 

SCL > SCL [> SCL] ... 

You will note that a minimum of two SCL components are required in a CL. The reason for 
his will be explained when we look at the three categories of SCL components. Also note that 
the > symbol is used to delimit the SCL components. 

The following is a synopsis of the SCL component: 

[ [netname::] hostname:] [*] command/file 

Notice that netname and hostname are optional, although if a network name is supplied, then a 
host name must also be supplied. In the case where both netname and hostname are specified, 
a double colon must delimit the netname and the hostname, and a single colon must delimit the 
hostname and the command/file. Further, if the command/fUe value contains a colon, then the 

hostname must be supplied at a minimum so that the colon within the command/fUe will be 
ignored by dncl. ' 

ZSLZT* n ° de ‘ S u hC , CUrrC J nt machine ( the netname and hostname combination 
represent the current machine), and no colons appear within the command/file value, then 

netname and hostname may be omitted. Similarly, if the hostname machine is on the current 

ne^nrt "TT T ^ ° mitted - ° n dnet 8 atewa y mach “ es remember that only one 
network is considered to be current. This means that although the network may be directly 

connected to the current machine, it can not be considered a current network. 

The command/file portion of the SCL represents either a file or a command to be accessed on 
the given machine and falls into one of three categories: 

• First SCL component - must be a file 

• Middle SCL component - must be a command (precede with *) 

• Last SCL component — must be a file 

he m p m ^i° m thC CL syn °P sis above > and minimum of two SCL components must 

form of f l ri H COm . ponent a " d a Last SCL component). This represents the simplest 
form of a dncl CL and results in a file transfer without filtering. The dncl CLs of greater 

complexity merely represent a higher degree of filtration between the first and last SCL 
components. The filtration described here is provided by the middle SCL component category 
(a command). This command is assumed to read input from a standard location, process the 
input received and generate output to a standard location. Many commands can be described in 
this fashion (input/processing/output), but not all work with standard locations for input and 
output. Commands that do use standard locations and work in the input/processing/output 
fashion are described as being filters. To work properly as a middle SCL category SCL 
component, the command must also be a filter, as unpredictable results will otherwise occurr. 
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DNCL(l) 


SCL™“ o^ C ato“ e80ry SCL com P°"' ms ”“*■ •» P'«‘ded ™>h an aste™ (<) as shown in the 

2*™“ ° perating fy stem is rich ^th existing filters to perform a variety of tasks These 
for VMS e Jirh 1 r a i rat ' Ve y “ the VMS 0perating s y stem - Despite this, filters may be created 

SUSSyoiJST pr08rams y “ sing ,h ' preder “‘ d s,d,n “ d s,d0 "‘ s s 

SEE ALSO 

dtftp(l), dsh(l) 

DIAGNOSTICS 

After successful completion of a dncl CL, the following message will be displayed: 

ACKCOMP received. 

ta Scr”cLttl h H ACKCO aT COMPietion) packet has been initia.ed by ,he 

components £ “J SSg tti^ ^ 

to be viS a ' 8 P “ Sib,y ,CmM n0d5 ' and lh “ mc “ age «■ Plated back 

A common form of error message is: 

No route to netname::hostname:dncld 

from the ™ location. Two things 

h h<T e been^Ld^ ******* ^ n ° dC namC P ° rd ° n ° f the s,ated SCL - thc default may 

2. The node is always relative to the node on the previous SCL component. The first SCL is 
always relat.ve ,o your current node. As an example, if the first SCL was specifed as 

second scl « ^ then * — 

CAVEATS 

Never make assumptions about current location within a file system on any node when creatine 
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DNETSTAT(l) 


NAME 


dnetstat - obtain dnet network status 
SYNOPSIS 


dnetstat [dnetjietwork] [dnet host) [-acdlhlnprs] 

description 


Infori^tion^may^^splayed 5 ^ varkius'fo^ 1 DNET - related d *a structures. 

dnetstat can be used to determine the status” f ah DNET 8 ^ ** ° Pt, ° n Whkh is specified - 
usage statistics. ° f aU DNET seivers - routul 8 tables, and server 


Information may be displayed for the local 
other DNET nodes. 


DNET node 


or may be retrieved and displayed for 


Options: 


ane network - the DNET network of the DNET host fror 
omitted, local network is assumed 


which information is desired; if 


dnet_host - the DNET network of thf* hnift c ,, , , 

network and host omitted, local host is assumed 6 ' n,0 ™ alio " “ desired; if both 

If none of the below options is specified, the defaults Inc.l hos, & [, dl „ e 

-a Display all available information (in long format) 

-c Display Status of Connection (Streaming) Servers 
-d Display Status of Datagram (Connectionless) Servers 

between machines with differed 3l) f ° mat; aUows °P tionaJ conversion 

-h Display help on options for dnetstat 


•1 Display other specified options in long or extended format 
-n show DNET map (network, host) 


-p ping the specifed host - i.e. test if DNET is alive 
options. If successful, the message: 


on the specified host p overrides all other 


DNET is Alive at dnet network dnet host 

;Pera,i °" “ — — * *— - 


Timed out waiting for response 


-r show DNET routing tables for the specified node 

-s show per-DNET server statistics (dtftp, drexec, dmail, dnd) 
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SEE ALSO 

dnstatd, tbls.msinitdec, tbls.msinitdec, tbls.net 

DIAGNOSTICS 

The call fails if: 

Specified host is not up 

DNET is not operating on the specified host 

dnstatd is not operating on the specified host 

In each of the above instances, dnetstat, will report: 
Timed out waiting for response 
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DREXEC(l) 


NAME 


drexec - dnet ’remote execution’ client 
SYNOPSIS 

drexec duet network dnet host 

DESCRIPTION 

DNE^r C ° mm f and pe, ; f ° rms a sim P )e rem ote execution function over the DNET network A 
DREXEC > 

StaSSj”"' a>mmi " ,dS Wl,iCh ^ b£ m ‘ Ur «°° d “ ’native’ e n vi,o» m e„ t of .he 


xxxxxx 


The drexec command provides a 
instructions on a remote machine. 


convenient means of executing simple command line 


The ability to run drexec depends 
destination host. 


on its presence in the Master 


Server Init Table for the 


Command line arguments 

dnet_nctwork name of the destination DNET network 
dnet_host name of the destination DNET host 

SEE ALSO 

dncl(l) 

diagnostics 
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DTFTP(l) 


NAME 

dtftp - dnet trivial file transfer client 
SYNOPSIS 

dtftp [dnetjietwork] [dnet host] 

DESCRIPTION 

The dtftp command allows the transfer of files to and from remote DNET machines 
Information may be displayed in various forms, depending on the option which is specified. 

othTr DNET TJdcs diSP ‘ ayed ^ ^ ^ DNET nod ® ° r may be retrieved and dis P ,a V ed for 


Command line options 

dnetjietwork name of the destination DNET network 
dnetjiost name of the destination DNET host 


Commands 
cd XXX 
get 
help 

led XXX 

Ipwd 

Is 

lls 

mode 

put 

pwd 

quit 

SEE ALSO 

dtftpd(l) 

DIAGNOSTICS 


change the default directory on the remote host to XXXX 

retrieve a file from the remote to the local host 

display help message for available dtftp commands 

change the default directory on the local host to XXX 

list the current directory on the local host 

list the contents of the current director/ on the remote host 

list the contents of the current director/ on the local host 

Allows specification of binary or ASCII mode 

transmit a file from the local to the remote host 

list the current directory on the remote host 

end the file transfer session 
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1. Introduction 


This Guide is intended to provide the information 
applications using the DNET Basic I/O package. 


necessary for a programmer to write DNET 


The generation of ’ordinary applications should be handled by the information in this euide. 

^ Sp ^ iaJ DNET applications and internal functions, such as Master Servers, 
Technical GridTand NetW ° rk Command Language Internals are discussed in the 


A discussion of DNET operation relevant to writing standard applications is presented first followed 

SK" mte T St 111 7 ltmg ClientS md sen ' ers - Hussions are followed by basic 

code templates and specific application examples which illustrate both streaming and connectionless 

m^es PPL ' 50 “ lduded are P rocedures for ’making’ DNET code on the various target 
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1.1 DNET Modes of Operation 


The basic function of DNET is to provide a reliable communication interface between any 
application pair (client/server) running over DNET. Depending upon the particular usage, this 
service may be viewed as employing either a client/server or a task/task model of operation, 
e task to task model assumes two (or more) arbitrary processes (tasks) on separate DNET 
< i 0 “®“ mcate mth on c another providing they follow DNET conventions and use the 
DNET basic I/O package or Network Command Language in order to communicate. The 
service is offered in both connection-based and connectionless modes. 


e connection based mode provides a dedicated channel with private gateways and relay 
processes. It provides high quality service, but requires that a set of processes be spawned and 

™T ODShe s P edflcaU y for this communication session. The connection based 

DNET service, establishes permanent virtual circuits between communicating tasks for the 
duration of the communication session. To use the connection based service, the function, 
dn openO , is required. It creates a circuit that supports DNET data streaming mode which is 
useful in applications such as remote login, where rapid, interactive processing is required 
Once such a streaming connection has been established, DNET becomes a "smart wire' 
between the communicating tasks; i.e. user program data moves over the open connection as if 
it were simply a hardwire link. The calls "dnwriteO" and "dn read()" may then be used to 
exchange data over the network. 


NET also provides a reliable, connectionless, datagram service. In connectionless mode 
processes may communicate with one another without any (apparent) need for a circuit 
connection to be established. Data are transmitted in units (datagrams) comprising data 
prefixed with headers containing source/destination information to be used by the 
communications software during the transmission of the data. 
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2. DNET Host Software 


“ descnbes the software components provided at DNET Hosts. Tliere are four major 

1. Overview of a DNET Host 

2. DNET Basic I/O Library Functions 

3. Supporting Software for the DNET Host 

4. DNET Applications 

More advanced software associated with DNET internals is discussed in the DNET Technical Guide. 

2.1 Overview of a DNET Host 


Any computer connected to one of the networks served by DNET 
provided the following conditions apply. A DNET host machine must: 


may become a node on DNET 


1. be resident on a specific existing network (e.g. TCP/IP Net X, SPANET, etc.) which DNET 
considers as one of its ’domain*' J 


2. have DNET Host Software Installed & Operational 

3. be "activated" by the local System Administrator (see DNET ADMINISTRATOR’S GUIDE) 
The elements in the DNET host are shown in the following diagram: 
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A brief description of these elements follows: 


3. 


Software Components 

1. DNET Basic I/O Package - this is a library of function calls which provides basic capability to 

^ DNET datagramS “ d *** “ d t0 estabUsh “ d DNET 

2 ' KJwtSfSSL 1 TOSfsSi “ d aUocation of 3,1 DNET 

DNET Application Clients (as may apply at particular host) - 

' E SriST* - • A sp^cbl command Ibe interpreter which 

allows DNET network commands to be invoked from the local machine. 

— File Transfer 

- Remote Login 

- Mail 

- Network Status 

DNET Application Servers (as may apply at particular host) - 

- DNET Network Command Server (NCS) - allows interpretation of DNET Network 
Commands distributed” from a DNET Network Command Interpreter 

- File Transfer 

- Remote Login 

- Mail 

DNET »S»£lu^"™ PrOVid “ “ tattrfa “ bCW “" *- “ d - «» 

° atagra “ S f rver / Tbe ^ ^ers provide interfaces to the underlying networks for 
” K a “ m ' tk0d “ *° “* “ -W- available b a 

DNET Network Status Server - This server uses the datagram service to provide status 
information in response to requests from the dnetstat network status client. 


4 . 


6 . 


7. 


Ibbles and Variables 

h Master Server Init Thble (tbls.msinittcp & tbkmsinitdec) - This is a file containing the 

Ae DNCT^™ 1 - 11 ? f V he SerVer ‘ 11 k loadcd bto the M ^ter Server Table when 

the DNET software is started on the local node. 

2. Master Server Ifcble - information on the server programs controlled bv a Master Server 
the Nfrater&xv “ d ^ to Master Server - ' This table is generated in memory by 

the Master Server Process based on contents of the Master Server Init Table. X Y 

3 ‘ ,^f T * These tables list detailed instances of Specific DNET servers 

under control of the Master Server at this DNET host. There is a separatfsiT for each 4e of 
seiver available at this node. These tables are internal to the Master Server but may be viewed 
using the dnetstat process (see USER’S and ADMINISTRATOR’S guides). * 

4. Routing Thble(s) (tbls.net) - table identifying the gateways from this host to every other network 
or to networks that lead to all the other networks. X ° rtc 

5 ' byXl/o" P^L?!id'th table C ° ntainin ? ** Channd nUmbers of virtual circuits used 

t>y the I/O Package and their correspondence to user program logical streams 
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6. Hostname Tfcble (tbls.mynamc) - File containing name of local node and its DNET network 

7. Services Files 

1. UNIX 


The standard file 
/etc/services 

must contain the following entries: 


5279 dms/tep # DNET PVC Master Server 

5279 dgsudp/udp # DNET UDP Datagram Server 


2. DEC 


For VMS Systems, the DNET master servers are automatically ’registered’ 
as network objects when DNET is started. 


2-1-1 Basic I/O Function Library 

The function calls provided in the DNET basic I/O library are summarized in the following table: 


Gtaerit Operation 

VIRTUAL CKT Client 

VIRTUAL CKT Stmr 

Datagram 

SIGNAL 

Estab. Connect* 

daopen 

dnget client 



Write 

dn_writ« 


dnewrite 

dn^signal 

Synth Read 

daread 


dneread 

Dest Oper Sys 

ASynch Read 



dacdg_handler 

Dest Oper Sys 

End Connect. 

da_cloee 

dadoM^dicloM 

da_edone 



These functions are described in the following sections according to the type of service (PVC 
Connectionless Datagram, or Signal) which they support. 9 


22 Client/Server Relationships in DNET 

Most applications which use DNET interact via conversations between a client process and a server 

T hu . SecUon des f lbes ** 8 en cral strategy by which such client-server relationships are 
established and operate within DNET. F 

227 Definitions 

- Client - initiating proass; DNET communications initiated by the client or processes which it 
starts, requests service from a distant server process; 
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Serw - local or remote process which provides the service desired by the client process- the server 
must be spawned prior to responding to a request for service from a client process; 

ST ;/ P c° CC “ ,OC ?^ 31 CaCh DNET h0St Which ^ requests from clients for 

? ? rvers wbch ““ PVC servicc - “eluding DNET PVC Relays at Gateways. 

Each Master Server listens on a well-known port on a specific underlying network. Hence, DNET 
gateway machines will contain master servers for each protocol actively used by DNET. 

DNET Datagram Master Server (DGMS) - an independent master Server located at all DNET 

data J^m Chme !i ** trannussion > reception, and/or relay of DNET connectionless 

datagrams and signals. Processes which wish to use the DNET connectionless service must pre- 
register wththe DGMS. Protocol Specific Datagram Servers - These servers provide protocol 
specific mterfaces to existing networks for the DNET connectionless service. P 


222 types of Clients 


Four major client "types" are expected in DNET: 

1. DNET Applications 

2. DNET Network Command Interpreter 

3. User Defined Clients (new DNET applications) 

4. Other existing Clients (possible future expansion); e.g telnet, FTP, etc. 

22.3 types of Servers 


There are two application server types defined within DNET: 

1 * JNET Application Servers - called by client processes, these service providers include a DNET 
Basic I/O package. For all these services (File Transfer, Network Command Server, other 
application servers) there is a process which spawns copies of them and assigns the copies to 

clients on request. This controlling process is the "DNET Master Server". 

2. Other Servers (user defined, etc.) - spawned via DNET network command server 
(net-OMnjierv) these servers do not contain the DNET Basic I/O Package. They depend on the 
network command server to interface with DNET. V 


224 Control of Servers 

pa^nWFT^ W < hi i reqUife streamin 8 «™ce "e under the control of the DNET Master Server(s) at 

h^7 kf!' SCrVCrS T* 1x5 Clther P res P awncd or spawned on demand depending on the 

type of host and local system considerations. 

connectionless service is also available to these servers if they register with the Datagram 
Master Server. Details of connectionless operations are provided in a later section. 


225 Number and types of Servers 

‘ DNET h °“ — * DNET servers 


The number and types of servers are determined by the DNET Master Server Table Init file: 
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This is a flat ASCII file. Entries in the file appear on separate rows and have the format as follows: 



The number of prespawned servers is specified in column 3. 

The Maximum (permissible) number of servers of this type is specified in column 4 
Column 5 contains the number of servers to be started when DNET is first started 
Servers may be added or deleted by editing this file (DNET admin privileges required) 
Further discussion of the significance of these entries is provided in the following sections. 


A separate Master Server Init File 
VAX which is connected to both 
tblsjnsinittcp and tbls unsinitdec. 


“ S *^* 2 ?°°* COnnection al a DNE T host. Thus, at a 
a TCP/IP and a DECnet Network, there must be two such tables 


2.2.5. 1 Pres pawning of Servers 

“ VAX 

^T^‘s^ Pr ' SP *™ d """* “ spedf “ d W Id, Tabic Hie described 


Possible algorithms for spawning and assignment are: 


t .of oyta of severs, according ,o Ure coded* of ,he 

Z ?l^l e Tr“ ly “ SCd Sp ™" ”*> Wh “ » «!««• a server. This is ,ke 
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22.5.2 Maximum Number of Servers 

This parameter controls the maximum number of simultaneous copies of a particular server which are 
allowed at the local host. This number can be adjusted by the system administrator according to 
conditions on the local system. 
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3. DNET Private Virtual Circuits Operation 


from Ae S t ^ Ual (strCaming) DNET establishes permanent connections on all hops 

from the client to the server process. In establishing the connections necessary for these private 
circuits, pnvate relay processes and private communications connections are used. The establishment 
of the reqmred connections and gateway relays can all be done using the standard DNET open 
WlUCh “ts up a chain of DNET PVC Relay process. dn openO operates by 
folding a connection request datagram through DNET from client to requested serve/ 

hrS/nr^ 6 ***** ^ thc . cotmcctioa rc< l uest datagram and open a connection to the next 
Uie r °“ tmg mformation “ the datagram. The private relay/gateway processes 
s P^ °NET application servers L are induL in Ihe 
‘ p **** ° f the connedion request datagram. In this way the private virtual circuit 

will be created by the Basic I/O package as it transmits the datagram and opens connections to 

^^fread^'^ 5565 ' (OPCDing 3 COnneCti ° n *° 8 prOCCSS ^ ««« the process to be spawned if it 


Once a private virtual DNET circuit has been established, data is transmitted and received using the 
functions dn_write() and dn_read(); usmg tne 

To dose the connections created for the private virtual circuits described above, the process that 
originated the connections simply calls the function dn_close() which causes the PVC to be dropped. 

t s “ ,he fo "“ wing *•— = A 
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The format of the connection request datagram is shown below: 

# 

Type = Connection Request 
originnet 
originhost 

origin_service (process) 
dest_net 
desthost 

dest^service (process) 
next_servtee 
callback (lag 
callbackjwrt 

callforward_stream (either channel or file descriptor) 

dnopenO returns a data stream to the client only when a virtual connection has been established with 
the desired server. Once dn openO returns successfully, the client and server may each use the 

functions dn_wnte() and dn_read() to read and write data streams to one another as shown in the 
following di agram - 


Field 

0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 
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The following diagram shows schematically what 
heterogeneous network example: 


a private virtual circuit would look like in the 
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PROCl 
DNET Client 



Net Q to Net XXX 


In this example, two DNET PVC Relay processes are employed, at gateways G1 and G2 in order to 
complete the virtual circuit. 


3.0.1 Client j Server Conversation 

Once the PVC is open data is streamed between client and server processes: 
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5.0.2 Closing a Client j Server Conversation 


At the conclusion of a session, the DNET 
dn_dose(). Either the client or server process 


permanent virtual 
may call dn_dose(). 


circuit 


may be closed by calling 
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4. Writing Connection Mode Services 


4.1 DNET Client Design Issues 

DNET Clients are executable processes located in the directory dnet_home/bin. This directory should 
be included in the user’s path for UNIX systems. On VMS systems, ’paths’ to each client are defined 
in the dnlogin.XX file which should be executed by the login.com file as part of the user’s login 
sequence. 

The following defines the procedure for writing ordinary application client processes. 

4.1.1 General Rules for Coding DNET PVC Client 

The general form for the coding of a DNET Application Client is as follows: 

#deflne SERVICENAME "dhackd" 

main 0 

{ 

User-Defined Initialization 

processname ■ "XXXXX" /* this is the mnemonic for the process */ 
dn initO 


chan = dn_open() 


Application Code 

dn_write(chan^„) 
dn_read(chan, ) 


dn_dose() 

return/exit/bottom of client loop 

> 

The several elements in this ’standard’ form are discussed in the following sections: 
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4.1.2 Detailed Discussion 

4.1.2. 1 SER VICE NAME and progname 

SERVICE_NAME is used to indicate the name of the server to which this client will connect. 
SERVICE_NAME is typically passed in the process field of dn open. 

progname defines the name of the client. This variable is used internally by the client and is used to 
name an optional ’log’ file. 

4. 1.2.2 User Initialization 

This is any application specific initialization at the option of the progr am mer 

4. 1.2.3 Initialization • dnJnitQ 

This is a mandatory function call which sets up the necessary run-time tables for the application. The 
global variable progname must be called. 

4.1.14 Defining a Virtual Circuit - dn_open() 

dn_open() is used by client processes to request a Private Virtual Circuit connection to the specified 
service a given network and host. The function does not return until a path to the destination has been 
opened or an error occurs (channel cannot be opened, timeout, etc). 


dnopen 

chan = dn_open(net, host, service) 

int chan; /* A channel number; 

used in subsequent read and write calls */ 
char ‘net; /* A DNET network name */ 
char ‘host; /* A DNET host name */ 
char ‘service; /* A DNET service */ 


Once dn_open() returns a channel, the PVC is assumed to be established. The ’open’ chan may be 
used as a ’file descriptor’ in DNET read and write operations. 


4.1.15 Using a Defined Virtual Circuit 

4. 1.2.5. 1 Blocking vs Non-Blocking Operations 

DNET read and write operations may be either blocking or non-blocking. Blocking operations are 
those which do not return until a certain event has occurred. Thus, a blocking ’read’ or ’write’ is one 
which waits until a specified number of bytes have been read or written, respectively. 

In non-blocking operations, the action may be initiated without waiting to determine if it completes. A 
non-blocking operation might also be a ’poll’ which simply checks for example, whether data has 
arrived and needs to be read. 


4. 1. 2.5.2 Reading and Writing on a Virtual Circuit 

DNET permanent virtual circuits service provides functions which closely approximate the UNIX 
system calls read() and write(). 
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dnwrite 

nbyites = dn_wrlte(chan,buf,nbytes) 


lot nbytes; 

lot chan; 
char *buf; 


/• The number of bytes, Including DNET headers, 
w»s written on tbe given stream. * / 

/* */° channel returned from dn open •/ 

/• Tbe data that is to be sent This Auction 
prepends tbe data with a DNET header. •/ 


dn read 


Synchronous (Blocking) read 


n bytes = dnread(chan, 
int n bytes; 

Int chan; 

char *buf; 

int count; 


buf, count) 

/* The number of bytes, including DNET headers, 
that was read from the given stream. */ 

/• A pointer to an I/O structure that was 
previously opened by dn openO */ 

/• A result parameter where tbe datagram, in 
string format, is placed; this buffer 
contains the DNET headers. */ 

/* The maximum number of bytes to receive. */ 


4.1.26 Closing a Virtual Circuit - dn_close( ) 


The function dn closeO closes 
and servers. 


a DNET PVC communications channel; it can be used in both clients 


dn_dose 

status = dnclose(stream) 

/* An Indication of success or failure */ 
/* A channel structure that was 
previously opened using dn openQ */ 


int status; 
int chan; 
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4.2 DNET Server Design Issues 

In network communications applications, the server the server can be either be permanent or transient. 
The choice is transparent to the client. 

A permanent server is one that is initiated at network start up time and when not otherwise occupied, 
listens for, accepts connections and performs services until the network is shut down. 

A transient server is one that listens for connection requests using one process and when a request is 
received, starts a process that is dedicated to the client. The listening process can either be one which 
performs a particular server application or it can be one that manages many servers, listening for 
requests to any of them and spawning or reactivating the appropriate servers. 

A communications server application can be permanent on one host (a VAX, for instance, where 
process start-up is slow) and transient on another (most UNIX systems, where processes start quickly). 
Control of pre-spawned and demand spawned processes is handled by the DNET PVC Master Server 
according to entries in the Master Server Init Table(s) discussed elsewhere. 

4.2.1 General Rules for Coding DNET PVC Server 

The following is the ’skeleton’ code for a DNET PVC Server: 

#deflne SERVICE_NAME "dhackd* /* name of server associated with this client */ 

mainO 

{ 

User Static Initialization 

progname = "dhack"; /• name of this server •/ 

dnlnltO; 

While ( chan = dn_getclient( ) ); 

User Dynamic Initialization 
Application Code 


dnj-ead(chan, ); 

dn_write(chan, ); 


dn_done(); /* notify MS that session is over; 

loop to getdient for another request */ 

return/exit/bottom of server loop 

dn_dose(chan); 

> 
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4.22 Detailed Discussion 

4.221 SERVICE J4AME & progname 

SERVICE_NAME is used to indicate the name of the server to which this client will connect. 
SERVICE_NAME is typically passed in the process field of dn open. 

progname defines the name of the client. This variable is used internally by the client and is used to 
name an optional log’ file. 

4.222 dnjnitQ 

Same role as for DNET Clients. 

4.223 dn j*etclient() 

The function dnjgetclientO performs a role for DNET servers parallel to than played by dn open() for 
DNET clients. The Idle’ server waits on dn _getclient() for notification of a service request from the 
Master Server. 

dnjgetdlent 

chan = dn_getclient (service, usrbuf, pusrbuffen) 
char* service; 
char* usrbuf; 
char* pusrbuflen; 


4.224 dnjmteQ / dnjeadQ 

Same function as for client. 

4.225 dn _done() 

dn_done 

dn done Is called by each DNET Application Server before exit 
to indicate to the local Master Server that it has 
completed Its task and Is available for use 

4.226 dn_close() 

Same function as for client processes. 


43 Connectionless Datagram Service in a Streaming Application (if 
required) 


DNET applications which arc primarily streaming based may nevertheless have need to use the 
optional connectionless service. This service may be used by following the rules outlined in the sections 
on DNET connectionless service later in this guide. 
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4.4 An Example Streaming Application 


DNET facilities a^e^Md* * ^ ypical dicnt / server P a * r (decho & dechod) written using the 

^ rCfcrred ^ DNET — - code listings for exaipt 

The user interface to decho is described in the DNET User’s Guide. 

^ th he 

“K P b^°o“the\Se o f rr e r which rctun,s a *° ^ ^ 

cr!iX™'sr red '” dCr “ itely ““ “ ° ( “» “ by 0* use, (CM-D for UNIX, 
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decho.c 


#deflne MAINPROGRAM 

#iacl»de <sldkUi> 

#include 'dad «rvJ^ 

# include "dneLfc” 

#iaclude "dnetemaoJi” 

#UdefDN EVMS 
#include <ffle.h> 

#c«ur 

#ttMDN EUNIX 
# include <fcntUi> 

#endif 

# define SERVICENAME "dechod" 

ninin(angc, ai*v) 
ini »rgq 

char *argv[]; 

< 

ini channel, fid; 

if (urge < 3) { 

4>rintf(stderr, Usage %s net node [ files ]0, argy[0]); 
return; 

> 


prognamc * "dec ho*; 

If (da_iaitO < 0) ( 

da •m>r("d» but*); 

«dt(l)| 

> 

4»rintf(stderr, 'ftying to open connection to %a %s«, argv[l], argr[2]); 

channel * da_opea(argv(l), aigv[2], SERVICE NAME); 

if (channd<t) { 

da «TOf<*da open*); 

«£(l)l 

) 

ferintflstderr, "Ready.0); 

lf(«r*c »« 3) 

edw(ehaanel, •); 
else { 

while (-ar*e >■ 3) { 

if ((fid » opeafargvfargc], 0_RD0NLY» « -1){ 
perror<argv|*r*c])7 
continue; 

} 

echofehaand, fid); 
clo*e(fid); 

> 

> 

da dose(channel); 
odt(0); 

> 
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acho< f haaa ii M) 

chaaaei, M| 


{ 


tkv 

iat 

while ((, 


baf(2*DN_BUFSIZ + 1], 


nad(U, K sfaaofrbof) - 1)) > »){ 
bwf(aread] » NULL, 
if (defrag) 

%nintf(s«d«rr, 'dec hoc tier read from stdia, 

if((« 


D) l» 


U%dO, 

I) 


> 


I ■ bm_wrtt«(chaMHd, bat strien(baf), 

break; 

if (debag) 

. ^ritfiXderr, 'dechec efrer da write, aseal i. 

tf ((meed «^forwrend(chaaaet bat skert(ba|) - L asent)) I- mtmt) 

it (defrag) 

d * r ’ **» mrrdU«<W, mevd): 

If ((MMOt » wrl»e(l, ba t, Breed)) »^d) break; 5 


> 

fcrcf wrll^chaji, but buflm, Com) 

i*t chu( 

char 

** buflen, force; 

Mbytes,!*; 

Mbytes « % 

whik (nbytes < fore# && abytes < buffca){ 

if ((r* « da_write(chaa, buf + abytes, 

bulk* . abytes)) < 0){ 
daerrorfdawrite”); 
return(-l); 

) 


i + * ret; 
if (Mag) 

4>rintf(stderr, "forcewrite force «%d nbytes =%d0, 
j fort *> nbytes); 

rctarn(iibytes); 

bm_rMd(chu, but; buflea, force) 
i*t ebaaf 

char *ba* 

i“f befln, force; 

iat Mbytes, ret; 

Mbytes * 0; 

while (Mbytes < force &* Mbytes < buflea){ 

,7* * <, "- r *“ d ( ch * B > b»f + nhjtee, buflm . nbytes), 

If (ret < •) ( 

da_errmr(*dM_read*); 


> 


■D? 


d)J(a 'fa ret; 
if (defrag) 

feriatftstdmr, "fcrceremk force «%d abytes -%<)•, 
force, nbytes); 


return(Bbytes); 
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/ 

dechod.c 


/ 

#d «fhtt MAINPROGRAM 

#incktd« < stdio.li > 

#iachMk*dMt env.h" 

#iacM* "dnetV 
liacMt ”dn*<_em*ajr' 

awia(ar|c, aigv) 

W argq 

ckv *«rgv[l 5 

{ 

lit channel; 

char debuglogIM]; 

FILE *fopen(); 

extern int vmserrnof 

progname = "dechod"; 

i t (da initO < •) 

«odt(l); 

setopdebug (debug, progname, getpidO); 
if (debug) 

ty>rintf(stderr,”decbod: calling dagetclknU))! 

while ((channel * da getcUent(progname v «, 6)) I* 4) { 
dec hod (channel); 
dn_cloM<channel); 
da done 0 ; 

> 

«dt(0); 

} 
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*chod( channel) 
intdnuaeh 
( 

'tar b«f[2*DNBUFSIZ + 1J; 

*■* arevd, meat; 


} 


whil«(l) { 

tf((are*4 • da^ea dlehaanel, hi sheoUbnl) . 1)) <- 0)< 

“ (<W*| &A arrvd m m §) 

.fa, if (mjf ^“T’ ,,nata8ti »" (’M)O, nrcvd); 

*ri«f(,tderr, —• ERROR — dechod: dn read tailed (%d)0, 
nrcvd); 


break; 

> 

if (debag) { 

*rintf(stderr, Macho* %d byte* read®, nrcvd); 

IvintfKrfcierr, Method: before dawriteO); 

if ((meat » dawritefchaanel, ba( nrcvd)) < - ®){ 

Jrtjrtlslderr, — ERROR — dechod: nseni(SM) <» 00, nsenl); 

} 

if (debug) 

4>rin(f(siderr, Method: <%d b*e») writtenO, men i); 
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5. Connectionless Mode Services 


5.1 Introduction 


are routed automatically via DNET Datagram Se™„ w Which 
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process. A completion routine must be defined which will include a to dn creadQ. 



5.1.1 Connectionless Datagram Formats 

The general format of a DNET connectionless datag ram is: 

struct udg 

{ 

struct node sre; 

struct node next; 

struct node dest; 

lot maxhops; 

lot type; 

long buflen; 

char buflD MAXDGJ; 

}; 

where the struct node is defined as: 
struct node 

char host[I MAXHNAME]; 
char netllMAXNNAME]; 
char proc[I MAXPNAME]; 


Although the udg.buf field is defined to be D MAXDG bytes long, the DNET will not assemble a 
datagram that is larger than D_MAXDG bytes long. Therefore, there are a number of bytes defined 
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5*2 Details of Datagram Services 

5.2.1 Registration with the local Datagram Master Server 

** CaUed <ater caU “S *•-‘>*0 ) by any process which wishes to use the 


^ ? rtr dn - dau0 h °" to - - ****” «<«. *, 

errors! ^ b *"* onto of the process »|„ „ su „ 


5.2*2 Sending q Dotogrcun 

A process which wishes to seed , dotagrttm must iodude the folbwh* elements within its code 

{ 

processname = "XXXXX" 
dnlnltQ; /* mandatory */ 


/* register with the DGMS 

V 

dn_dnit0; 


/* populate sre and destination or datagram 

udg_s.src.host = "daevax"; 
udgs^rcjiet = "spanet”; 
udg_s.src.proc = "hacksender"; 


udgs.desLhost = "dac3b2"; 
udgs.desLnet = "dnettl"; 
udg_s.dest.proc = "hack receiver"; 


/* write the datagram 

V 

dn_cwrite( ); 


/* De-register with the DGMS 

V 

dn cdone 0; 

} ' 
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dn_cwrite 

dn_cwrit*(udg r, flags) 

struct udg_r *udg; 
lot flags; 

dn_cwriteO is used by DNET processes to send connectionless 
datagrams to other DNET processes* 

This operation is always synchronous. 


5.2. J Receiving Datagrams 

DNET connectionless datagrams may be received both synchronously and asynchronously. 

5.13.1 Enabling Datagram Reception Each process which need* m , 

connectionless datagrams must use the following format * *° reCC,VC 


{ 

processname = "XXXXX* 


/* mandatory •/ 

dncinitO; 


dn_cread(udg41ags); - may be called asynchronously using Signal or asynch read 
routine under appropriate circumstances (see text) 


dn_cdone(); 


} 


5.13.2 Synchronous Datagram Reception 

stsrtsft 'X tag 

condition is detected. Thi* , ‘ ^ not return ““bl a datagram arrives or an error 

no “ " a no "- ,,lod ‘ i,, ‘ <“ poUi “ e, 


dn^crcad ( u dg_r, flags) 

struct udg r *udg; 
int flags; 
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5.13.3 Asynchronous Datagram Reception 

The asynchronous reception of DNET datagrams is used when the DNET process is likely to be 
involved in other activities when a datagram arrives. In this situation, datagrams may be viewed as 
interrupts to the mam process. Such a view requires the specification of an interrupt handler which 
amply describes what (software) steps should be taken when a datagram arrives. Depending on the 
logic, this handler may selectively accept/reject arriving dat agr am^ 

The handler is specified by calling the function: 

dn_chandler(dhandle, daiertsig, udg ) 
where dhandleO 

Is the interrupt handler (interrupt completion routine), 
d_aiert_sig is the si gnal 

used to notify the main process of datagram arrival 
and 

udg points to a DNET datagram structure. 

53 Return Receipt Service 

A provision is made for return receipts for DNET datagrams. The process which sends a datagram 
and wishes a ’receipt’ needs to set the ’return receipt’ flag when railing dn cwriteO. 

dn handler must read the receipt flag in datagram and return receipt to calling process via return 


5.4 Signalling Services 

Sig n a lling between processes is viewed as a special case of the connectionless service within DNET. 
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5.4.1 Sending a Signal 

5.4.2 Receiving a Signal 
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5.5 A Connectionless Service Example 

An example, of the use of the connectionless service is provided in this section. The exam ple is an 
elementary 'sig n a ll i ng * application. The client process bed sends the text message "ABORT" in a 
connectionless datagram to a network, host, process specified on the command line: 

bed network host process 

The server process abc is a 'trivial' process which is started, then idles waiting for an abort message 
from a bed process. ° 

Following is the source code for the client process. 

/* 

* Module: bedx 

* Version: 1.19 

* Delta Date: 5/31/89 13:49*38 

V 

#lnclude "dnet_envJi" 

* define MAINPROGRAM 

#indude <stdloJi> 

#indude "dneLh" 

#indude "dnet_errnoJi" 

/* This redefinition of the user datagram structure in the user’s 

* will be replaced by providing the dn_alloc function to the user */ 

main (arge, argv) 
int arge; 

char *argv[]; 

{ 

char *getenv(); 

struct udg *udg; 

static char udgbuffer[512]; 

udg = (struct udg *)udgbuffer; 

if (arge != 4) ( 

fprintf(stderr, 'Usage: %s destnet desthost destprocO, argv[0]); 
exit(l); 

} 
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strcpy(udg- > desLnet, argv[l]); 
strcpy(udg->destfao8t, argv[2]); 
strcpy(udg- > destproc, argv[3]); 
strcpy(udg- > but; •ABORT); 
udg- > buflen * strien(udg- > buf) + 1* 
debug = 0; 

progname = ’dmskill"; 
fprintf(stderr, •dmskill: before dn dnitO); 

if (dn_cinit(progname) = = -1) { 

dn_cerror(); 
exit(l); 

} 

fprintf(stderr, •dmskill: before dn cwriteO); 

if (dn_cwrite(udg, 0) = = -1) { 

dn_cerrorO; 
if(dn_cdone()) 

dn cerrorO; 

exit(l); 

} 

if(dn cdoneO = = -1) 

{ 

dn_cerror(); 

exit(l); 

> 

fprintf(stderr, "OKO); 
exit(0); 

) 


“f m >'“sferred from tie command line into 

appropriate fields m the user datagram, udg. The "ABORT" message is placed in the datagram s 


•“ DMagr “ — — • — *--*» * cahed 
Finally dn_cdoneO ^ called to de-register bed with the Datagram Master Server. 


The server process code is presented below: 
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f* 

* Module: abcx 

* Version: 1 22 

* Delta Date: 5/31/89 13:4936 

V 

#indude "dnet_envJi" 

# define MAINPROGRAM 

#indude < stdio.h > 

#ifdef DNEUNIX 
#lndude < signal Ji> 

#endif 

#indude *dneth* 

#ifdef DNEVMS 
#lndude <ssdefJi> 

#cndif 

#indude "dnet_errno.h" 

char udgbufler[512]; 
struct udg *udg; 

main (argc, argv) 
int argc; 
char *argv[J; 

{ 

int rtncd; 

void dghandlerO; 

DEpush("main"); 

udg = (struct udg *)udgbufler; 
debug = 0; 
progname = argv[0]; 

#ifdef DN_EUNIX 

rtncd = (int)signal(SIGCLD, SIG IGN); 

#endif 

/* 

if (dn dnlt(progname) = = -1) { 

V 

fprintf(stderr,*$fcs: calling da dnit.0, progname); 

rtncd = dn dnit(*abc*); 
fprintf(stderr,"dn cTnit: returns^)); 

fprintf(stderr,”%s: dn cinlt returns %<L0, progname, rtncd); 
if (rtncd = = -1) { 

dncerrorO; 

DEpopO; 

odt(l); 

> 
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fyrintf(stderr,*%s: dncinit successful .0, pro gname ); 

If (dn_chandler(dghandler, SIGUSR1, udg) = = -1){ 
dncerrorO; 
if(dn_cdoneO * = -1) 

dn_cerror(); 

DEpopO; 

exit(l); 

} 

#ifdef DN EUNIX 
pause (); 

#cndif 

#lfdef DNEVMS 
sys_hlberO; 

#endif 

lf(dn cdoneO * 3 *1) 

{ 

dncerrorO; 

DEpopO; 

exit(l); 

> 

fprintf(stderr, exitlngO, progname); 

DEpopO; 

odt(0); 

} 


void dghandlerO 

{ 


DEpush("dghandler”); 

fprintf(stderr, "in dghandlerO); 

If (!strcmp(udg- > buf, "ABORT")) 

fprintf(stderr, "Received ABORTO); 

#ifdef DN EVMS 

if(sys_wake(0) = = -1) 

fprintf(stderr, "%o: Can’t wake up ./n", progname); 

#endlf 

DEpopO; 

return; 


Salient points in this code include; 

1. dncinit is called to register abc with the Datagram Master Server 

2. dn chandler is called; the signal SIGUSR1 is specified as the asynchronous signalling mechanism 
in eating arrival of datagram destined for abc, a completion routine dghandlerO is specified for 

“ re “ iTCd * 1 “ d Uk: <toagram “*> “ s P« ir “ :d » 1» target for 

3. The process ’idles’ using pauseO or sys_hiber() until a datagram is received 

4. dn_cdone is caUed to de-register with the Datagram Master Server prior to exiting 
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Tbe “* °?^ S *“ h * «“ ? ta. arrived. 

»p tie idling ml proc^tSn^ “ *" “ re “ lve * th ' ■““»« «*« 


5.5.1 Datagram Protocol Servers 


DST at Pr0t0C01 * 1 ?"*^ °? S i “* DNET processes located at each DNET host which propagate 
data^ams through the heterogeneous network. These servers provide a network pS 
specific interface between the Datagram Master Server (DGMS) and the underlying networks) An 
overview of a the relationships between the DGMS and DOS's is provided in the footing diagram: 



Network 1 


Network 2 


5.5.1.1 Connection Lock Table 

^J* t . agr | am j e ’ rvers kcep t™* of a P°° l of °pen connections to other DNET hosts over which 
ectionless datagrams may be routed. This information is contained in the Connection Lock Table 

The connection lock table contains information about the hosts to which the local host has connections 
dat^rams to'dul host “* '° S '“ 1 °"" b " “ ed * "* BAS,C >/° i° traasminiag 


Connection Lock Tabk | 

Connection Owner 

Stream ID 

Net 

Host 

Proe Name 

Channel # 

FXFRl-Clkrn 

1 

D 

4 

FXFR4 

89988419 

FXFR1 -Client 

2 

Q 

3 

FXFR4 

*9988419 

FXFRl -Client 

3 

T 

3 

FXFR2 

89988419 

— — 

— 

1 — 

— 

— 

- 


r — 

— 

— 

— 


— 

— 

— 

— 

— 


v 

— 

_ 

— - 

— 

— 
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5.6 Signalling 

DNET processes may send signals to other processes within DNET by calling the function dn signal(). 

5.6.1 Sending Signals 

dn_signal 

status = dn_signal(net, host, service, signal) 
int status; 

Int signal; 
char *net; 
char *host; 
char *servke; 

dnsignal sends a signal datagram to a server on a specified host 

5.62 Delivery of Signals 

DNET signals are sent to the Datagram Server at the destination host. The Datagram Server 
recognizes the type SIGNAL and forwards the appropriate information to the local operating system 
tor action. The operating system will complete actions such as ’killing’ a process, etc. See the Chapter 
on Connectionless Service for more detailed information. 
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6. DNET Error Handling 


DNET Basic I/O Library functions return 
operation: 


a non-selective error code if an error is detected during their 


DNET applications which wish to use the error handling facility should 
anet^ermo. h and follow the procedure below: 


include the header file 


Errors detected by the DNET code are identified in the variable dnet ernw: 
dneterrno = XXXXX; 


Anerror function, dnet_error('strlng»), is then optionally called where string is an optional, user 

^^-“ Tor pro,ides tafonM,io " - co " ditioos wh '° ^ — 


dnet_error(*error_strlng) 
char * error string; 

Detailed error codes are provided in an Appendix to this Guide. 
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7. Routing 


T °f ag SChemC - Eadl DNET nodc a routing table which lists the 
. . . “ode to contact m order to reach each known network within DNET. A ’null’ entry for the 

^ hoa “ *“* -—-I >0 iw dab*. 

from appik * t ”“ “ d h ““ - « * 

JSSSJX** hOS ' / '’ rOCCSS “ WtiCh <Uta * ra " «“ *« ttammiKed »« by calling ,he 


path = getjwthfsrcneMrchostydestnet.desthostydestprocess.numhops); 

src_net is the network in which the destination host is loca te d 
src host is the destination host 

dest net is the network in which the destination host is located 

desthost is the destination host 

destjprocess is the destination process 

numhops - number of hops from current location to destination 


Details on routing within DNET are found in the Adminstrator and Technical Guides. 
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8. Interprocess Communication 


tT* DNET pr0vides a generalized interprocess communication facility 
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9. Presentation Layer Services 


DNET will provide a limited presentation layer facility. 

only be viewed consistently if data types are faithfully "mapped" between machines. Y 

^rst C th^wi t thil^f ine ^ iDtegerS aS32bk qUantitics ^presents floating point 
numbers with 64 bits while the receiver represents these two data types as 64 and 48 hit nnlnfiVL 

respectively, serious misalignment of data files will occur. q antlt,es ’ 

The Presentation Layer Service to be provided by DNET will be limited to a subset of the SUN fXDR^ 
External Data Representation Protocol and the existing DAVID Presentation Services. 


9.1 XDR 

A***, of the SUN Microsystems External Data Represeotatio. (XDR) protocol is provided with 
XDR allows arbitrary c data elemeots to be written and read in a consistent and accurate manner 

z? suss SoT^s^ruSafi 

b)s r0 ^^^^^ rU ^F* *^^^“ a ^" 1 “ a ^*^^“ tc ^ 0 “r^^ C ^ er enees^iKh e m thiTnumber of 
its and/or the byte ordering of specific data types are conveniently avoided via judicious use of XDR. ' 

Jipica! XDR library functions include filter routines for strings (null terminated arravs of bvtesl 
structures, unions, and arrays as well as primitive routines for most common data types. These niter 
r outin es , are , used for both encodmg and decoding of Urn XDR canonicTd^stST TCe 
code/decode direction is indicated via a flag when the filters are invoked. 


Data may be encoded/ decoded source/destination data "stream", 
array, of a memory block. 


This stream may be a file, a memory 


9.1.1 Issues in the Use of XDR 


^ d DlS^° n ^° ,,/d ^ dr ^ -/common/dnxdrJ, contain the XDR functions available for use 
SSlSllS. ■ * t0 1116 ,0TO “*** for additional dcta * on the various issues 


The general procedures used for encoding/decoding of data with XDR are as follows: 
1. Specification of the XDR ’handle’ 
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2* Creation of I/O Data Stre am 

3. Encoding/Decoding of Data using XDR Library functions 

9.1.2 The XDR Handle ( Control Structure') 


A common structure is used to ’control’ the XDR operations on 
structure is shown below; 


a particular data stream. 


This 


/* The XDR handle. 

V 

typedef struct { 

enum xdrop x_op; /* operation; fast additional nnram */ 
struct xdr ops { 

ini (*x_getlong)0. 
lnt (*xjputlong)0. 
int (*x_getbytes)0, 
int (*x_putbytes)0. 
uint (*x_getpostn)0; 
bool t (*x_setpostn)(); 
long * (*xjnllne)0; 
void (*x_destroy)(); 

} *x_ops; 

caddr t xpubllc; /* users’ data */ 
caddr t xprivate; /• pointer to private data •/ 
caddr_t x_base; /• private used for position info */ 
h>t x handy; /* extra private word •/ 

int x size; /• yet another •/ 

} XDR; 


/• get a long from underlying stream */ 
/* put a long to " •/ 

/• get some bytes from ■ •/ 

/* put some bytes to ■ •/ 

/* get byte offset from beginning */ 

/* reposition loc in the stream*/ 

/* put some bytes to ■ */ 

/* free privates of this xdr stream */ 


9.1.3 Creation of the I/O Datastream 


Two functions may be used to create the XDR datastream. 
stream is to be a file or an area of memory. 


The function used depends on whether the 


File 


xdrstdio_create(xdrs, fp, x_op) 
XDR *xdrs; 

FILE *fp; 
enum xdr op x op; 


x op is chosen from among: 

XDRENCODE 
XDR DECODE 


Memory 
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xdrmemcreatefxdrs, addr, len, x_op) 

XDR *xdrg; 
char *addr; 
u_int lea; 

enum xdr op x op; 

x_op is chosen from among: 

XDRENCODE 
XDR DECODE 


9. 1. 4 Encoding I Decoding of Data using XDR library 

9.14.1 Primitive Filters Example of a typical primitive: 
bool_t xdr_xxx(xdrs, fp) XDR *xdrs; xxx *fp; { 

} 


Comments: 


xdrs points to the XDR control structure 
tp points to the data stream 

ENCODE/DECODE already specified in the XDR control structure 

Returns TRUE (1) if successful 
Returns FALSE (0) if failure 


The primitive names are usually adequate to describe the data type involved. e.g : 
xdr_long(&xdrs, stdln) 


9. 1.4.2 Non-filter Primitives 

“ eM ''" ai0,,S a “ 0W « *«i»g ament position in the XDR 

Get current position In the datastream 

u_int xdr jgettpos (xdrs, pos) 

XDR ♦xdrs; 
u_int pos; 
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Set current position 

bool_t xdr_setpos(xdrs, pos) 
XDR *xdrs; 
u_int pos; 


9.1.4.3 Higher Level Filters Arrays 


9. 1.4.4 An Introductory Example 


Consider the following simple example. The name of a file and 
between machines with consistent interpretation* 


its size, in bytes, is to be passed 


We define a structure in which to place the file information and 
used to populate this structure. 


assume that some convenient utility is 


struct 

{ 

char [100] filename; 

long filesize; 

} filedescrip; 

hoolt xdr_filedescription(xdrs, filedes) 

XDR *xdrs; 

struct filedescrip *filedes; 

{ 

return ( xdrstream(xdrs, &filedes-> filename) && 
xdr_long(xdrs, &filedes-> filesize) ); 
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Source; 


/* Dectare an Instance of the XDR ’handle’ 
XDR xdrs; 


/* open the ’Canonical’ File 

V 

fp * fopen ("Fileinfo*, V); 

/• Setup the xdr handle to point to ’Fileinfo’ and to encode the 
dates (ream 


•/ 

xdrstdlocreate (&xdrs, fp, XDRENCODE); 

/• Encode the file information (from file struct) into the open datastream 
fUedescription(&xdrs, fp);, 

/* Close the rUe 

V 

fciose(fp); 

/* Send the file to its destination using a convenient function 
putfUeQ; 
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Destination: 

/* Declare an instance of the XDR ’handle’ 

V 

XDR xdrs; 

/* Receive the file at Its destination using a convenient function 
receivefileO; 

/* open the ’Canonical’ File 

V 

tp * fopen ("Fileinfo", V); 

/* Setup the xdr handle to point to Tlleinro’ and to decode the 
datastream 

V 

xdrstdiocreate (&xdrs, fp, XDR DECODE); 

/• Encode the fUe information (from file struct) into the open datastream 
fUedescription(&xdrs, fp);, 

/* Close the file 

V 

fclose(fp); 


9.1.5 Example - use of XDR in dnetstat 

We next consider an example drawn from the actual DNET implementation. The DNET client/server 

pair dnetstat and dnstatd use XDR in order to accurately pass DNET status structures across the 
heterogeneous network. 

The ’standard’ XDR library function, xdnnem_create(), is used to create a data stream at a specific 
location m memory, m this case in the data buffer of a DNET connectionless datagram which is being 
assembled for shipment to the dnetstat client. B 


The steps performed are: 

1. Populate the data structure for the network status 

2. Create a temporary memory area (in the buffer for a DNET connectionless datagram 

3. Invoke a function which encodes/decodes the data structure to/from XDR format 
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struct udg udg s; 
struct dmsinfo dms stat; 

mainO 

{ 

XDR xdrs 

xdnnem_create(&xdrg, udgs->buf, sizeof (udg_s->buf), XDR ENCODE); 
xdr_sitJnstance(&xdrs,&dnM stat); 


Discussion 


xdrmem_create() is set up to place the XDR encoded structure in the data buffer (usg s->buf) of a 
NET ronnectionless datagram which is being assembled in memory for shipment to'some remote 


Since dnetstat is a designed to be a currently used DNET application, its accurate interchange of 
information warrants special attention. The functions xdrsitlnstanceO and xdr adgut instance!) 

Z CTC , C ^ om . wntten for ^ purpose. These functions and the data structures which they 
Encode/Decode are presented below; y 


struct ms entry { 

char service [80] ; 
char image[80]; 
int prespawned; 

int mar; 

int avail; 

int inuse; 

int seqno; 

struct si_entry •si table; 
}; /* for generic table •/ 

struct msinfo { 

char service [80]; 

char image [80]; 

int prespawned; 

int max; 

int avail; 

int inuse; 

int seqno; 

}; /• for generic table */ 
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struct sientry { 

lot pid; 

int inuse; 

int ini ted; 

long stime; 

struct msentry *ms entry; 

lot term sent; 

lot pending; 

Int bufkn; 

char buf[BUFSIZ]; 

}> /* for instance table */ 

struct silnfo { 

int pid; 

lot In use; 

int inited; 

long stime; 

int termsent; 

int pending; 

}; /* for instance table */ 

typedef struct ms entry MS ENTRY; 
typedef struct si entry SI ENTRY; 

# define DMS GETCLIENT 1 
#define DMS~GETSTATUS 2 

struct dms request { 
int pid; 
int type; 

}; 

# define DMSTAT END 0 

# define DMSINFO 1 

#deflne DMSTAT INFO 2 

struct dmsinfo { 

int type; /• DMSTAT INFO, DMSTAT END */ 

int numsl; " ~ 

struct ms info ms; 
struct silnfo si[100]; 
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/• structure for ADGUT (connectionless service) entry 

struct d gms adut 

{ 


intpid; /• Process Identifier •/ 

char pname[D_MAXPNAME]; /• Process name bound to */ 

dmr ipcnamefD MAXPATHNAME] ;/• Name of IPC mechansim for sending •/ 

intipcld; /* ipcid of ipcname */ 

intmaxmsg; /• Maximum number of bytes that this user can handle */ 

int signal; /• Signal number used to inform oT impending message •/ 

unsigned wtimeout; /* Timeout period on write •/ 

time t add time;/* Time adgut entry was added •/ 

time t lastaccess; /* Time adgut entry was last accessed •/ 

time_t lastjipdate; /• Time adgut entry was last updated */ 

time t last send; /* Time last datagram was sent to this process */ 

time t last recv; /• Time last datagram was received from this process */ 

int state; /• 0 - Invalid 


1 - Bask 

2 - Listen •/ 
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/* dnetstat utilities - User Network Status Function 

*/ 

#include < stdioJi > 

#indude <ctypeJi> 

# include "dnet envJi" 

#indude < signal Ji> 

#ifdef DNEUNIX 
#include <fcntlJi> 

#ifdef DN3R2 

#include "/usr/netindude/sys/timeJi" 

#else 

#indude < sys/timeJi > 

#endif 

#endif 


#ifdef DN_EVMS 
#ifdef DNDFTNIC 
#indude time 
#else 

#lnclude "time.h" 

#endif 

#endif 

#include "dnetii" 
#indude "dnet errno.h" 
#indude "dnet_ipcJi" 
#indude "dgmsJi" 
#indude "dmsJi" 
#indude "dnetstaLh" 

# include "dnxdrJi" 
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/* Connection Service Definitions 

V 

xdr sit lnstance(xdrs,dms bptr) 

XDR*xdrs; 

struct dmsinfo *dms bptr; 

{ 

char *cpp; 
lnt 1; 

if (!xdr_int(xdrs f &dms_bptr->type) ) 

return (FALSE); 

if (lxdr_int(xdrs,&dmg_bptr- > numsi) ) 
return (FALSE); 

cpp * dmsbptr- > ms^ervice; 

if (!xdr_strTng(xdrs,&cpp,D_MAXPATHNAME)) 
return(FALSE); 


cpp = dms_bptr> > ms Jmage; 
if (!xdr_strfng(xdrs,&cpp,D_MAXPATHNAME)) 
return(FALSE); 

if (!xdr_int(xdrs,&dms_bptr->ms.prespawned) ) 

return (FALSE) ; 

if (!xdr_int(xdrs^kdms_bptr- > ms jna x) ) 
return (FALSE); 

if (!xdr_lnt(xdrs,&dms_bptr- > ms .avail) ) 
return(FALSE); 

if (!xdr_int(xdrs,&dms_bptr- > ms Jnuse) ) 
ret urn (FALSE); 

if (!xdr_int(xdrs,&dms_bptr->ms.seqno) ) 
return(FALSE); 

if (debug) 

fprintf(stderr,*xdr slt instance: numsi = %dO,dms bptr- > numsi) 

for (1=0; i< dms_bptr-> numsi; i+ +) { 

if (!xdr_int(xdrs^Scdms_bptr- > si [1] .pid) ) 
return (FALSE); 

if (!xdr_int(xdrs,&dms_bptr* > si [i] Jnuse) ) 
return(FALSE); 

if (!xdr_int(xdrs,&dms_bptr- > si [i] Jnited) ) 
return (FALSE); 

if (!xdr_int (xdrs,&dms_bptr- > si [I] .stime) ) 
return(FALSE); 

if (!xdr_int(xdrs,&dms_bptr- > si [i] .term sent) ) 
return (FALSE)f 

if (!xdr_lnt(xdrs,&dms_bptr-> si [i] .pending) ) 
return (FALSE) ;~ 

} 

return (TRUE); 
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xdr_adgut_lnstance(xdrs,adg bptr) 

XDR *xdrs; 

struct dgms_adut *adg bptr; 

{ 

char *cpp; 

If (!xdrint(xdrs,&adg bptr->pld) ) 
return (FALSE); 

cpp = adgbptr- > pname; 
if (!xdr_strtng(xdrs,&cpp,D_MAXPATHNAME)) 
return (FALSE); 


cpp = adgbptr- > Ipcname; 

If (!xdrstring(xdrs,&cpp,DMAXPATHNAME)) 
return (FALSE); 

If (!xdr_int(xdrs t &adg bptr->ipcid) ) 
return (FALSE); 

if (!xdr_int(xdrs,&adg_bptr- > maxmsg) ) 
return (FALSE); 

if (!xdr_int(xdrs^adg_bptr-> signal) ) 
return (FALSE); 

if (!xdr_u_int(xdrs,&adg_bptr- >w_ timeout) ) 
return (FALSE); - 

if (!xdrlnt(xdrs,&adgbptr- > add time) ) 
return (FALSE); 

if (!xdr_long(xdrs,&adg_bptr- > last access) ) 

return (FALSE)7 

if (!xdr_long(xdrs T &adg_bptr->last update)) 
return (FALSE); 

if (!xdr_long(xdrs,&adg_bptr- > last send) ) 
return (FALSE)7 

if (!xdr_long(xdrs,&adg_bptr- > last recv) ) 

return (FALSE)7 

if (!xdr_int(xdrs,&adg_bptr- > state) ) 
return (FALSE); 

return (TRUE); 


9,2 Transferring arbitrary files using XDR 

No supporting mechanisms are currently offered in DNET for the problem of transferring arbitrary 


9*3 Existing DAVID Presentation Service 

pasting DAVID system currently includes a pair of data conversion functions which map data types 
mto a straightforward, virtual format for interchange with machines employing different internal 
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9.3.1 Virtual Data Format for DNET Transmission 


ASCH representation 


COMPSTATUS dcp_tpack(vca,cca,nvisit,tca,ptca,fptr) 
VCA *vca; 

CCA *cca; 

USHORT ’nvisit; 

TCA ‘tea; 

TCA *ptca; 

FILE *fptr; 


COMP STATUS dcp_tupack(vca,cca,fptr,ptrfile) 
VCA *vca; 

CCA *cca; 

FILE *fptr; 

FILE *ptrfilc; 
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10. Standard DNET Code Organization 


10.1 Standard Directory Structure 

The ’standard’ DNET directory structure is shown in the figure below: 


•./../dnet = dnetjxome 

/common /pvcdir /dgdlr /appdlr /bin 

NOTE; Programming tasks covered by this Guide should generally require modifications to files in 
../dnet/ and ~/dnet/appdir 

Changes to the subdirectories ../common, ~/dnet/pvcdir, ~/dnet/dgdir should only be undertaken 
with a view toward global changes in mind. 

10.2 Variation for VMS Installations 

The DNET directory-tree on VMS systems is logically identical to that on UNDC systems. It differs 
only in the syntax used to reference directories: 

dnethome: [.common] 
dnet_home: [.pvcdir] 
dnet_home: [.dgdir] 
dnethome: [.appdlr] 
dnet_home:[.bin] 


Standard DNET Code Organization 
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11. Compiling & Making DNET Applications Programs 


11.1 General Strategy 

Use existing DNET applications as a model for make files 

The relevant libraries in dnet_home directory are placed in the dnetjxome directory. 

11.2 Setting DNET Compile Time Environment Variables 

These Environment variables are ordinarily set automatically based on the machine name provided to 
the DNET postmove utility program. Typical of the environment to be specified are: 

1. Communication Protocol(s) 

2. TCP/IP Implementation 

3. Target Machine Type 

4. Target Operating System 

The most convenient means of setting these variables is to create an entry for the target DNET 
machine in the file dnetjxome /tbls.db. This is a database file which contains all relevant information 
about the target node. 

113 Making UNIX Version 

1. cd dnet home 

2. make 


11.3.1 BSD Systems 

Special considerations - Must run ’ranlib* manually on the libaries generated during the ’make’ 
procedure. 

ran lib dneta 
ranlib dnettcpji 

This may be accomplished by running ’make’ twice on the target machine; this has the effect of running 
ranlib twice. 

11.3.2 Example Make File 


A typical UNIX makefile is show below. This file is used to make the DNET application files. All 
relevant makefiles are presented in the source code listings. 
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$(CC) -c S(CFLAGS) $< 

$(AR) S(ARFLAGS) $@ $•. 0 

rm -r$*o 

S(GET) S(GFLAGS) $< 

$(CC) -c S(CFLAGS) $*x 
$(AR) $(ARFLAGS) $@ $*.o 
rm -f $*. [coj 

DNET * „/dneta 
DNETTCP = „/dnettcpui 
DNETDEC = ~/dnetdec.a 
CDIR = ./common 
BIN = „/bin 

#DNETDG s ./ dgdir/libdn dgji 

HEAD=S(CDIR)/dneLh $(CDIR)/dnet_envJi $(CDIR)/dnet_errno.h $(CDIR)/dnet_ipc.h $(CDIR)/dnxdr.h 
ak*“ ar 

ARFLAGS=rv 

CFLAGS=-g -I$(CDIR) -DDN3B2 -DDN ETCP 
CCLINK*cc S(CFLAGS) -o $@ $@ x J(LIBS) 

WOOL = /usr/IIb/libneLa /usr/llb/libnsl sjt 
LIBS =$ (DNETTCP) $(DNET) $(WOOL)~ 


all: 


nd: 

echo: 

login: 

mskill: 


echo mskill netstat rexec tftp nd login mall 
$(BIN)/dmail $(BIN)/dmaild $(BIN)/cbeckdmaU 
$(BIN)/dnd $(BIN)/dndd $(BIN)/dndd_unix 
$(BIN)/decho $(BIN)/dechod $(BIN) /dechon 
$(BIN)/dlogin $(BIN)/dlogind 
S(BIN)/dmskill 


netstat: $(BIN)/dnetstat $(BIN)/dnstatd 


pbmc $(BIN)/drexec $(BIN)/drexecd 

tftp: $(BIN)/dtftp $(BIN)/dtltpd 
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$(BIN)/decho: decbo.o $(DNET) $(DNETTCP) 

cc -o $(BIN)/decho decbo.o $(LIBS) 

$(BIN)/dechod: dechod.o $(DNET) $(DNETTCP) 

cc -o $(BIN)/dechod decho<Lo $(LIBS) 

$(BIN)/dechon: dechon.o $(DNET) S(DNETTCP) 

cc -o $(BIN) /dechon dechon.o $(LIBS) 

$(BIN)/dmskill: dmsUll.o $(DNET) S(DNETTCP) 

cc -o $(BIN)/dmskiU dmskiU.o $(LIBS) 

$(BIN)/dnetstat: dnetstato dnstatutiLo $<DNET) $(DNETTCP) $(CDIR)/dgmsJi $(CDIR)/dms.h dnetstat.h $( 

cc -o $(BIN)/dnetstat dnetstato dnstatutil.o $(LIBS) 

$(BIN)/dnstatd: dnstatd.o dnstatuULo $(DNET) $(DNETTCP) $(CDIR)/dgmsJi $(CDIR)/dms.h dnetstat.h $(C 

cc -o $(BIN)/dnstatd dnstatd.o dnstatutil.o $(LIBS) 

$(BIN)/drexec: drexec.o $(DNET) $(DNETTCP) 

cc -o $(BIN)/drexec drexec.o J(LIBS) 

$(BIN)/drexecd: drexecd.o $(DNET) $(DNETTCP) 

cc -o $(BIN)/drexecd drexeccLo |(LIBS) 

$(BIN)/dtftp: dtftp.o dtftputlLo dnlog.o $(DNET) S(DNETTCP) 

cc -o $(BIN)/dtftp dtftp.o dtftputil.o dnlog.o $(LIBS) 

$(BIN)/dtftpd: dtftpd.o dtftpuUl.o dnlog.o $(DNET) $(DNETTCP) 

cc -o $(BIN)/dtftpd dtftpd.o dtftputil.o dnlog.o $(LIBS) 
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$<BIN)/dpresent: dpresenLo $(DNET) S(DNETTCP) $<CDIR)/dgmsJi $(CDIR)/dmsJi dpresent.h 

cc -o $(BIN)/dpresent dpresenLo $(LIBS) 

$(BIN)/dmall: dmaiLo sendmaiLo readmaiLo dtftputiLo $(DNET) $(DNETTCP) $(CDIR)/dneLh $(CDIR) /d 
cc -o $(BIN)/dmail dmaiLo sen dmaiLo readmaiLo dtftputiLo $(LIBS) -leurses -Itermcap 

$(BIN)/dmaild: dmailcLo dtftputiLo $(DNET) $(DNETTCP) $(CDIR)/dneLh $(CDIR)/dms.h S(CDIR) /dn 
CC -o $(BIN)/dmaild dmaild.o dtftputil.o $(LIBS) 

$(BIN)/cbcckdmail: checkdmaiLo $(DNET) $(DNETTCP) $(CDIR)/dneLh $(CDIR)/dms.h $(CDIR) /dn 

cc *o $(BIN)/checkdmail checkdmaiLo $(LIBS) 

$(BIN)/dnd: dncLo dndutils.o $(DNET) S(DNETTCP) $(CDIR)/dneLh $(CDIR)/dmsJi $(CDIR) /dnet err 

cc -o $( BIN) /duel dncLo dndutils.o $(LIBS) 

S(BIN)/dncld: dnd<L© dndutils.o $(DNET) S(DNETTCP) $(CDIR)/dneLh $(CDIR)/dms.h $(CDIR) /dnet er 

cc -o $(BIN)/dndd dncl<Lo dnd utils.o S(LIBS) 

$(BIN)/dndd_unis dndd_unix.o dnd utils.o $(DNET) $(DNETTCP) $(CDIR)/dnet.h $(CD1R) /dms.h $(C 
cc -o $(BIN)/dncld_unix dnc!d unix.o dnd utils.o $(LIBS) 

$(BIN)/dlogin: dlogjn.o diogutils.o $(DNET) S(DNETTCP) 

cc -o $(BIN)/dlogin dlogin.o diogutils.o $(LIBS) 

$(BIN)/dlogind: dlogind.o dlogutiIs.o S(DNET) S(DNETTCP) 

cc -o $(BIN)/dlogjnd diogind.o diogutils.o $(LIBS) 


decho*o: 

$(HEAD) 

dechodo: 

S(HEAD) 

dechon.o: 

$(HEAD) 

dmaiLo: 

$(HEAD) dmailJi 

dma f 

$(HEAD) dmailJi 

dm.sk 

$(HEAD) 

dnetstato: 

$(HEAD) dnetstaLh 

dnstatcLo: 

S(HEAD) dnetstaLh 

dnstatutil.o: 

$(HEAD) dnetstaLh 

drexec.o; 

$(HEAD) 

drexeccLo: 

$(HEAD) 

dtltp^K 

$(HEAD) dtftpJa 

dtftpcLo: 

$(HEAD) dtftpJi 

dtftputiLo: 

$(HEAD) dtftpJi 

dnloguK 

S(HEAD) 

dpresento: 

$<HEAD) 

dloghuo: 

S(HEAD) 

dloginduK 

S(HEAD) 

diogutils.o: 

$(HEAD) 

dncLo: 

S(HEAD) dndJi 

dnd<Lo: 

S(HEAD) dncLh 

dndd_unix.o: 

$(HEAD) dndJi 

dndutils.o: 

$(HEAD) dndJi 
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11.4 Making VMS Version 

11.4.1 General 

DNET currently employs VMS ’command’ files as a pseudo ’make’ facility. These files are simply 
scripts for executing the various steps necessary to ’make’ DNET on the target VAX machine. Since 
this is not a true make facility, these files DO NOT check for the date of executables versus source files, 
requiring instead that the user keep track of incremental changes in the source code and the ’side’ 
effects of these changes on the several executables. 


11.4.2 MicroVAX II 

1. cd dnet_home 

2. @make.dv 

$ define cSinclude dnet^common, dnet_pvcdir, dnet_dgdir, wool_sys, - 

wooI_netinet $ define vaxcSinclude cSinclude, sysSlibrary $ lib/create dnet $ lib/create dnetdec $ 
lib/create dnettcp $ cd [.common] $ @decnet.m $ @tcp.m $ @vms.m $ cd [-.pvcdir] $ @dnet.m $ 
@drelay.m $ @dmsjn $ cd [-.dgdir] $ @mall $ cd [-.appdir] $ @decho.m $ @dechon.m $ @drexec.m S 
@dtftp.m $ @dmskill.m $ @dnstat.m $ @dlogin.m $ @dncl.m $ @dmail.m $ cd [-.bin] $ purge *.exe $ 
S cd dnet_home $ 

The makefile for decho is presented below as a representative example of making a specific 
application. 

11.4.3 NASA-GSFC VAXes ( IAF f DFTNIQ etc. using Excelan TCP) 

Enter the following commands 

1. cd dnet_home 

2. @make.dft 

11.5 Making individual files 

It is obviously possible to make individual files via manual steps or via selective ’makes’ of either the 
common, pvcdir, dgdir, or appdir makefiles. It is important to note that there are numerous 
interactions between the ’ewe’ DNET files in common, pvcdir, and dgdir. Any changes to these files 
may have wide ramifications and considerable functional testing of all DNET operations is advised 
after such tests. 

DNET applications which follow the basic rules in this GUIDE are more ’self-contained’ and may 
usually be altered without significant effect on other applications. 
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12. Debugging DNET applications 


For convenience, a generalized ’logging* facility is provided in order to allow a 1st order indication of 
DNET operations. This may be used as a ’debugging* aid when problems arise with DNET and the 
user is unfamiliar with the specific debugging tools on the local machine.. 

This facility is activated when the DNET "environment variable" is set. This varies with the operating 
system as follows: 

1. UNDC 

shell dnet_debug= l;export dnet_debug 
C shell setenv dnet_debug 1 

2. VMS 

define/job dnet_debug 1 

The debugging files will be placed in the directory and named as follows: 

Directories: 

UNDC 

/tmp/dnet 
VMS dnet_home 

The log files are generated for each DNET server process (most clients will ’dump* messages to the 
terminal instead of a file) and are named as follows: 

XXX###.log 

where XXX is the process name 
and ### is the process ID 


UNDC files may be viewed while DNET is operational using 

On VMS systems, DNET must be stopped before the log files may be inspected. 

NOTE: 

Care should be exercised In the use of this debugging technique as log files of considerable size may 
be generated over time* Thus the ’debug* option should only be activated long enough to study a 
problem, then deactivated by setting dnctjdebug ~ 0 
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13. D NET Error Codes 


# define D NOERR 0 

# define DSYSERR 1 

# define D~BADSTATE 2 

# define D BADARG 3 

# define D~OVRFLW 4 
# define D AEXIST 5 
# define D~ESRVRSP 6 
# define D EPERM 7 
# define D NOMSG 8 
#deflne DNODGRSC 9 

# define DINTERN 10 

# define DBADNM 11 

#deflne DDGTB 12 

#define DMSGTB 13 

# define DBADHN 14 
# define D~ADGENF IS 
#deflne DPN2BIG 16 
#deflne D IPCNM2BIG 17 
#define DNOEXIST 18 

# define DINTR 19 

# define DNOSRSC 20 
#deflne DNODNET 21 
#deflne D~WOULDBLOCK 

# define D~TIMEOUT 23 

# define D QUOTA 24 
# define D NOSYSFILE 25 
#deflne DSYNERR 26 
#define DNOIMAGE 27 
#define D HOMELESS 28 
# define D~SRVNOACK 29 

# define D~NOHOST 30 
#define D NOPATH 31 
#deflne D~SYSLIBERR 32 
#deflne DNODNETSRV 

# define D SHUTDOWN 34 
#define DMAXERRS 35 


/•No DNET error*/ 

/* A system error has occurred •/ 

/* program In wrong state to issue this dnet call */ 

/* value of argument was determined to be invalid */ 

/* overflow of i/o buffer •/ 

/* The specified object already exists */ 

/* Error return value In DGMS service req response */ 

/* Permission Denied */ 

/* D NOWAIT flag set and no message waiting to be read */ 

/* No more available DGMS resources */ 

/* Internal DNET error •/ 

/* Invalid process name was specified */ 

/* Datagram To Big */ 

/* Message To Big */ 

/* Could not find net/host combination in router tables */ 

/* ADGUT Entry Not Found •/ 

/* Process name string too big */ 

/* I PC n a me string too big. DNET code error */ 

/* The specified object does not exist */ 

/* A signal interrupted the library routine */ 

/* Temporarily out of system resources */ 

/* Missing all or part of dnet provider */ 

22 /* Operation would block */ 

/* Timeout or retry count exceeded •/ 

/* Quota limit exceeded */ 

/* DNET system file/table not found */ 

/* DNET system file/table syntax error */ 

/* Image (server) not file not found */ 

/* Env variable ’dnet home’ not defined */ 

/* No res pone from application server */ 

/• No such host */ 

/* DNET could not find a path for the sre/dest pair */ 

/* System library function felled •/ 

33 /• DNET servers dms/dgstep not defined in ’etc/services’*/ 

/* Orderly shutdown from master server */ 
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static char *dgms errmsgs[D MAXERRS] * { 

"No DNET error", 

'A system error has occurred*, 

•program in wrong state to issue this dnet call*, 

"value of argument was determined to be invalid", 

"overflow of i/o buffer", 

"The specified object already exists", 

"Error return value in DGMS service req response", 
"Permission Denied", 

"D_NOWAIT flag set and no message waiting to be read", 

"No more available DGMS resources”, 

"Internal DNET error", 

"Invalid process name was specified", 

"Datagram To Big", 

"Message To Big", 

"Could not find net/host combination in router tables", 
"ADGUT Entry Not Found", 

"Process name string too big", 

"I PC name string too big. Probably DNET internal code error", 
"The specified object does not exist", 

"A signal interrupted the library routine", 

"Temporarily out of system resources", 

"Missing all or part of dnet provider”, 

"Operation would block", 

"Timeout or retry count exceeded", 

"Quota limit exceeded", 

"DNET system fUe/table not found", 

"DNET system fUe/table syntax error", 

"Image (server) file not found", 

"Env variable ’dnethome’ not defined", 

"No respoue from application server", 

"No such host", 

"DNET could not find a path for the src/dest pair", 

"System library function tailed", 

"DNET servers dms/dgstcp not defined in ’/etc/services 
"Orderly Shutdown from master server” 

}; 
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14. Glossary 


The following terms are used in the description of DNET: 

Applications Servers- 

Servers such as File Transfer, Remote Login, Remote Execution, etc. that perform 
services for clients. Applications Servers are invoked on demand by clients after using 
the Service Assignment to obtain the name of an available server. 

Connection Lock Thble- 

List of open connections held by process for use by its Basic Datagram I/O package. 
Locked connections result from user requests for Permanent Virtual Circuits. 

Datagram Master Server (DGMS)- 

A server process, located at each DNET host and gateway, which provides an interface 
to DNET clients and servers and the DNET Connectionless Datagram and Signalling 
Service 

Datagram Protocol Servers (DPS)- 

Protocol specific servers located at each DNET host and gateway, which provides an 
DNET Connectionless an interface to the underlying network Datagram service. 

Master Server Init Ihble- 

These tables, tblsjmslnittcp and tblsjnsinltdec contain initialization information for 
the DNET Master Servers including the type of server to be activated, the maximum # 
allowed at this host, and the number to make available initially, and an indication of 
whether the server must be prespawned. The tables are updated by the local System 
Administrator at the specific DNET host. 

Master Server Ihble- 

One for each DNET host, it contains information on the types and numbers of each 
class of DNET server actively supported on this node at any instant. Each generic 
server entry points to a Server Instance 1 hUe which lists the current specific instances 
of a particular class of server. It is updated by the Master Server and by specific 
DNET application servers. 

Master Server Process (DMS)- 

Proc esses, one per Network, managing the Master Server Table, handling server 
registration, server assignment, and server control. They are spawned by network 
start>up command files. 


DNET Basic I/O package- 
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Included as library within an application program, it provides network i/o interface 
including datagram formatting. 


Gateway- 


A DNET node at which communicaton protocol boundary is passed. DNET relay 
servers move data from one network to another performing an effective protocol 
conversion for streaming services. These servers are created, allocated, and used like 
any other DNET streaming applications servers. The Datagram Master Server, in 
conjunction with protocol specific datagram servers performs a similar function for 
DNET datagrams. 

Network Command Line Interpreter- 

DNET Client process that directs the execution of network commands using 
datagrams sent to various hosts and several servers. 

myname • hostname table- 

A table, this .myname, maintained in the dneMiome directory on each DNET node 
lists the DNET networks to which that host is connected and the name(s) by which the 
local host is known on those networks. 


Network Command Language Processor- 

Server that directs the execution of network commands using datagrams sent to various 
hosts and several servers. It is an application server, copies can be pre-spawned or 
spawned on demand. 

Network Command Server- 

Spawned by request from Command Language Processor, this Server is directed by 
Command Language Processor. It spawns processes and directs i/o to execute network 
commands. 

Network Status Server- 

Resides b each network host. Receives Host Status Tables, Host Alias Table, Well 
Known Server Tables, Connectivity Tables, and periodically sends "I am alive" 
messages to the Administrative host. To ensure these periodic messages are sent the 
Basic datagram I/O package uses a timer/wake-up signal to initiate the transmission 
of the message to the Network Status Client. Because this is done by the I/O package 
and there is a copy of this package b every process that uses network I/O the network 
status data is collected on a per process not per host basis. 


PVC Relay 


A DNET relay used b the completion of DNET Permanent Virtual Circuits (PVCs). 


Relay 


Special DNET application processes located b a DNET gateway which perform 
protocol conversion for DNET streaming service between dissimilar networks. The 
appropriate Master Server process ’listens* on a particular protocol boundary when 
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idle and a li gns a relay when a request for a protocol h’hop* is received from DNET.. 
The relays are nam ed according to the protocol boundary which they are intended to 
bridge. Thus a T-D relay services requests which arrive on a TCP/IP network, 
relaying data to a DECnet net. Relays operate in a full duplex mode while actually in 
use. 


Router 


DNET employs a hierarchical routing strategy. Each DNET node has, for every 
(DNET) network known to it, information on the next DNET host to contact in order 
to move data toward the de stinatio n. The DNET router function uses the information 
in the routing table as follows: Given a destination network, host, and process, returns 
the next ’best’ hop (network, host, process) to ’move* toward the destination. 


Routing Thble- 


A hierarchical routing table that contains the next ’hop’ from the local DNET 
host /network in the direction of all other DNET networks. A m inim al version of this 
table is provided with the distribution copy of DNET. The table is currently 
maintained m anuall y by the local system administrator. In the future, this table will be 
dynamically configured and maintained by the local DNET Network Status Server 
after intiai startup has taken place. The routing table is named tblsmet and is located 
in the dnet_home directory. 

Server Assignment Function- 

Returns the name of an available server to a requesting Router, and updates the 
Domain Server Table. 

Server Instance lhble(s- 

Lists the current specific instances of a particular class of DNET Application Server. 
Entries are made by the Master Server and cleared via dn_done() calls from the 
servers as they complete their tasks. 

Server Registration Function- 

This function is part of the Domain Server Process. It updates the Domain Server 
table with information from Servers (e.g/now in use"). 
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NAME 


dn_cdone - Free up user resources associated with a datagram communication endpoint. 
SYNOPSIS 

int dn_cdone() 

DESCRIPTION 

The dn_cdone library routine performs the cleanup of any resources allocated by dn cinitGU') 
and/or dn_chandler(3U). ~ ’ 

Because the DNET Datagram Services are not implemented from the kernel, there is no 
feasible method for cleaning up after the user application unless explicately told to do so by the 
user application through the dn_cdone library routine. Because many of the datagram 
resources are stored in a shared user process, failure of the user applications to use the function 
will result in wasted space and resources to the point that no applications will work. 

SEE ALSO 

dn_cinit(3U), dn_chandler(3U) 

RETURN VALUE 

A value of 0 will be returned on success, and a value of -1 will indicate an error. 

ERRORS 

The call fails if: 

[D_BADSTATE] The dn cinit function was not called previous to invoking this function. 
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NAME 


dnchandler - Prepare for the asynchronous receipt of datagrams. 
SYNOPSIS 

#include "dneLh" 

int dn_chandler(dhandle, d_alert_slg, udg) 
void (*dhandle)(); 
int d alert sig; 
struct udg *udg; 

DESCRIPTION 


IxctDdo?hTnHlin libra 7 f ° f tinC 15 USCd Pr0Vide 3 St3ndard iDterface for the declaration of an 
exception handling routine for receiving datagrams asynchronously. 

The address of your exception routine (a standard C function) is passed along with the address 

of thT a . 3 f 3m structure ( ud 8)- ( Ref er to the description of dn_cread(3U) for a description 
of the user datagram structure.) Upon the receipt of a datagram, the normal thread of acdvity 
of your program will be interrupted while the datagram is placed in the user datagram structure 

LdneTSlfecT 1 The * a ddn “T#’ ^ successfull y read «g *e datagram, the exception 
outine is called The address of the user datagram structure is passed as the only anmmenr 

fe!umed tUrnmg r0Utine ’ the normal thread of activity of your program is 

In UNIX, the second argument is the signal number used to inform the library routines that a 

1 1 Eh Urf r-f SigD f al Sh ° Uld n0t be 056(1 for any other Purpose withL your pro^am 

UP ° n ! he T 31 nUmber ChOS6n ’ * 15 ‘Hat either 

GUSR1, or SIGUSR2 is used. This signal number is ignored in VMS implementations. 

™;; XeC T g Wi ? i " °J ° n behalf ° f your exce P tioi » routine in UNIX environments, further 
ndications of pending datagrams will be ignored. Before returning control to the normal 
.hread of actmt, wtthtn your program, though, the librtuy routines will ensure , hat uo 

hS pe " d '“ 8 ' °" e Sl 8 nal lhe ". may result in multiple invocations of the exception 

handling rout.* before control is returned to the normal thread of activity nfS 
environment provides for stacking of events which could have in similar results. 

SEE ALSO 

dn_cinit(3U), dn_cread(3U) 

RETURN VALUE 


A value of 0 will be returned on success, and a value of -1 will indicate an error. 
ERRORS 


The call fails if: 
[DSYSERR] 
[DAEXIST] 

[DBADARG] 

[DBADSTATE] 

[DBADNM] 


A system error has occurred. Check the global variable errno. 

The process name that was requested to be bound to is already bound 
by a process in the state associated with Listen DGMS Service. 

The value of d_alert_sig was not in the range: (1-32) 

The calling process was not in a proper state to issue the dn chandler 
function call. This error is identified by the dgms. 

The process name as bound to in the dn_cinit call was registered at the 
dgms as being null. 
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CAVEATS 


fl ? data 8 ram structure that you provide must be big enough to hold the biggest datagram 
t may arrive. The D MAXDG constant may be used in combination with the dn sdloc 
library routine to create a structure large enough to hold i he largest allowed datagram. “ 
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NAME 


dn_cinit - Create a datagram communications endpoint. 
SYNOPSIS 

int dncinit(pname) 

char *pname; /* Optional specification of name to bind to */ 
DESCRIPTION 


The dn_cinit library routine establishes a datagram communications endpoint over which 
datagrams may be received or sent. 

If th f. e . ndp ^ nt is to be used for re ce'Pt of datagrams, a pname (process name) must be 
specified. This pname is the character string equivalent of the TCP/IP port number. A 
datagram is addressed via a network name, host name, and process name. The latter is used 
once on the proper machine to determine which dnet datagram server to send the datagram to. 

The dn cimt routine will fail if the requested pname is already in use by another datagram 
service . 

An empty string may be passed as an argument but will result in an endpoint not capable of 
receiving datagrams The argument should, in all cases, point to a valid memory location to 
avoid an unrecoverable run-time error condition. 


SEE ALSO 

dn_cdone(3U) 
RETURN VALUE 


A value of 0 will be retur led on success, and a value of -1 will indicate an error. 

ERRORS 


The call fails if: 
[DSYSERR] 
[D_NODNET] 
[DNOEXIST] 

[DNOEXIST] 

[DBADARG] 

[DAEXIST] 

[DNODGRSC] 

[DQUOTA] 


A system error has occurred. Check the global variable errno. 


The above two errors are indication that the dgms process is not 
currently running. 

An internal error has occurred where the dgms process could not access 
this process. 

An internal error has occurred. 

Another datagram service has already established an endpoint bound to 
the requested pname. 

The dgms is temporarily out of all allocated resources. This error may 
occur as a result of failure of datagram services to issue a dn cdone 
successfully before ending. 

Your quota limit has been exceeded. This should never occur with the 
current implementation since multiple datagram communications 
endpoints are not allowed. 
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NAME 

dn_close - close a dnet communication channel 
SYNOPSIS 

int dnclose(chan) 
int chan; 

DESCRIPTION 

The dn_close user library routine closes the dnet communication channel: chan. 
SEE ALSO 

dn_open(3U) 

RETURN VALUE 

A value of 0 will be returned on success, and a value of-1 will indicate an error. 
ERRORS 

The call fails if: 

[DSYSERR] A system error has occurred. Check the global variable errno. 
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NAME 


dn_cread - read a datagram from a datagram communications endpoint. 
SYNOPSIS 

#include "dnet.h" 

int dncreadfdg, flag) 
struct udg *dg; 
int flag; 

DESCRIPTION 


The dncread [library routine provides a method for reading datagrams synchronously, or within 
the normal thread of execution of your program. The dg argument should point to a user 
datagram structure large enough to hold the incoming datagram. 


The default action of the dn cread routine is to block until a datagram arrives, if an outstanding 
datagram does not exist. If this is not desirable, then the flag may contain the DG F NOWAIT 
bit set which will cause the dn cread to return in error if no datagram is outstanding. ~ 

The following is a description of the user datagram structure: 


struct udg 

{ 

struct node src; 
struct node next; 
struct node dest; 

long maxhops; /* maximum number of bops before failure */ 

int type; /* user defined type */ 

long buflen; /* length in bytes of buf */ 

char buf[l]; 

}; 


struct node 

{ 

char host[I_MAXHNAME]; 
char net [I_MAXNNAME] ; 
char proc flMAXPNAME] ; 


bv^ d rh eSS ° f Ch f- USCr i a J agram ' S described in the d * st “ode. The src and next nodes are set 

The srr b no7 T' .“*? "° de is ° f transient significance to the datagram service itself. 

Ime from Thk a nelH &X ™ med , by tbe *<; rver application to determine where the datagram 

f d 15 stam P ed b y the ,lbrar y routines on the way out and overwrites anything 
placed in it by the user routine. 7 K 

°l thc d * St f ield Sh ° u,d be filled in ^ the application before attempting to send the 
datagram. No methods exist for sending broadcast datagrams of any form. 

The maxhops field is used to avoid errors in the routing tables which might cause a datagram to 

endlessly loop in attempt to get to it’s destination node. This field is currently ignored as this 
service has not yet been provided. ^ ** lIUS 

The type field is currently not used by the system, although the range of types: (0-31) should be 
considered to be reserved types and should not be used. The type field is provided so that the 
user may have a standard mechanism for categorizing datagrams in whatever fashion needed. 


Page 7 


(08/10/89) 



DN_CREAD(3U) 


DNET 


DN_CREAD(3U) 


The buften field specifies the number of bytes of data in the buf field. The buf field is not 
limited to ASCII data, so special characters may be passed as part of the datagram. 

The buf field hold the actual contents of the datagram. You may note that the buf field is 
defined as being one character long. The purpose of this is to allow the datagram applications 
o decide how long this fiild should be. This may be done by using the dnsalloc library routine 
to define an appropriately sized buffer and return an address which may be placed in a udg 
structure pointer variable. 6 

SEE ALSO 

dn_cinit(3U), dn_cwrite(3U), dn_chandler(3U), dn_cdone(3U) 

RETURN VALUE 

A value of -i will indicate an error condition exists and the external variable dnet errno can be 
checked to identify the error. A positive integer will represent the number of bytes contained in 
the message read. 

ERRORS 


The call fails if: 
[DSYSERR] 
[D_SHUTDOWN] 


[DNOMSGJ 


A system error has occurred. Check the global variable errno. 

A shutdown message was received from the dgms. An attempt clean up 
vail be attempted by the library routine and the datagram 
communications endpoint will be removed. The shutdown mechanism 
is not currently implemented and so this message should not be 
received. 

The DG_F_NOWAIT flag was set and there were no outstanding 
datagrams. 


CAVEATS 


If the ipc mechanism used to communicate between the library routines and the dgms process 
fills up because of neglect, the dgms will begin discarding any newly received datagrams until 
there exists enough buffer space in the ipc mechanism to hold the entire datagram The only 
indication of the datagram discarded as a result of this will be a terse error message in the dgms 

processes error output. This, though, is not the only possible cause for loss of datagrams in this 
unreliable datagram service. 

™ e . a P pl ‘ Cat,on ™ ust insure that the user datagram structure represents a buffer big enough to 

DNNtAXnr 51 dat t agr f a f m that m1 ^ b e received. The dn_salloc routine may be used with the 
DN MAXDG constant to create the buffer necessary to hold the largest possible datagram. 
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DN_CWRITE(3U) 


DNET 


DN_CWRITE(3U) 


NAME 


dn_cwrite - Send a datagram to a remote process. 

SYNOPSIS 

#include "dnet.h" 

int dn_cwrite(dg, flags) 
struct udg *dg; 
int flags; 

DESCRIPTION 

The dn_cwrite function call facilitates the sending of the datagram pointed to by dg to a remote 
process. Refer to the description of dn_cread(3U) for a discussion of the udg structure. 

The flags argument does not currently have a use at the user level. 

The datagram service is inherently unreliable. It is therefore the responsibility of the user 
processes to insure receipt. 

SEE ALSO 

dn_cread(3U) 

RETURN VALUE 


A value of 0 will be returned on success, and a value of -1 will indicate an error. 
ERRORS 


The call fails if: 


[DSYSERR] 

[D_BADSTATE] 

[DSHUTDOWN] 

[D_DGTB] 


A system error has occurred. Check the global variable errno. 

You have not successfully called dn_cinit yet. 

A shutdown indication has been sent by the dgms process. 

The buflen field was greater than the maximum allowable size of the 
entire datagram structure. The entire datagram structure must be less 
thanD MAXDG. 
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DN_DONE(3U) 


DNET 


DN_DONE(3U) 


NAME 


dn_done - connection services server completion routine 
SYNOPSIS 


int dn_done() 
DESCRIPTION 


SEE ALSO 


This connection oriented user library routine should be called by all servers when they are 
brushed servicing a particular client. An IPC mechanism is opened to the master server that 
tells the master server that this server is finished and ready for a new connection. 


dn_getclient(3U) 
RETURN VALUE 


This routine returns the number of bytes written to the master server on 
-1 is returned to indicate that an error occurred. 

ERRORS 


success, and a value of 


The call fails if: 

[D_INTERN] The call was unable to inform the dms module that it was available. 
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DN GETCLIENT (3U) 


DNET 


DN_GET CLIENT (3U) 


NAME 

dn_getclient - Wait for a connect request from a remote client. 

SYNOPSIS 

int dn_getclient(service, usrbuf, pusrbuflen) 
char *service; 
char *usrbuf; 
int ♦pusrbuflen 

DESCRIPTION 

The dn_getclient user library routine is called by a permanent server when it wants to establish 
a connection with a client which has requested its service. 

The service argument points to a character string representing the name of your server. The 
usrbuf and pusrbuflen arguments describe a buffer in which the connection request message 
will be replaced which will contain the node identification of the requesting client. 

If no requests are outstanding, this routine will block until a connection request arrives. 

SEE ALSO 

dn done(3U), dn_close(3U) 

RETURN VALUE 

A positive value will be returned on success representing the channel descriptor back towards 
the requesting client. A value of -1 will indicate an error. 

ERRORS 

The call fails if: 

[D^SYSERR] A system error has occurred. Check the global variable errno. 
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DN_INIT(3U) 


DNET 


DN_INIT(3U) 


NAME 


init - initialize connection based dnet services 

SYNOPSIS 

#include "dnet.h" 

int dnjnit() 

DESCRIPTION 

This internal library rout ne is the dnet initialization function. It is called once after setting the 
progname, dlog and debug values. This function loads the nyname and network tables into 
memory. 

RETURN VALUE 

This routine returns a value of 0 on success and a value o ' -1 to indicate that an error occurred. 

ERRORS 

The call fails if: 

[D HOMELESSJ The dnet_home environmental variable was not set. 

CAVEATS 

If dn_cinit is called from within your program, this routine should not be used. 
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DN_OPEN(3U) 


DNET 


DN_OPEN(3U) 


NAME 


dn_open - create a dnet communication channel 
SYNOPSIS 


int dn_open(destnet, desthost, destproc) 
char *destnet; 
char *desthost; 
char *destproc; 

DESCRIPTION 


SEE ALSO 


nrnr , J P ' " S t [ T llbrar y/o utine establishes a dnet communication channel between the calling 
procedure and the specified server process on the specified host on the specified network Thf 
server process will have previously issued the dn_getdient routine. The function does not 
return until the channel has been successfully established to the destination. 


dn_write(3U), dn_read(3U), dn_close(3U) 
RETURN VALUE 


A positive value will be returned on success representing the channel number 
communication channel. A value of -1 will indicate an error. 


of the established 


ERRORS 


The call fails if: 

[D_SYSERR] A system error has occurred. Check the global variable errno. 
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DN_LOGIN(3U) 


DNET 


DN_LOGIN(3U) 


NAME 

dn login - verify username password for access to services on a node 
SYNOPSIS 

dn_login( ) 

DESCRIPTION 

This library routine is used by DNET client processes which need to . 

RETURN VALUE 

This routine returns a value of 0 on success and a value of -1 to indicate that an error occurred. 
ERRORS 

The call fails if: 

CAVEATS 
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DN_LOGIN_VERIFY(3U) DNET DN_LOGIN_VERIFY(3U) 

NAME 

dn_login_verify - verify u« ername password for access to services on a node 
SYNOPSIS 

dn_Iogin_verify( ) 

DESCRIPTION 

This library routine is used by DNET server processes which need to verify that the current user 
has access privileges on the local DNET host. 

RETURN VALUE 

This routine returns a value of 0 on success and a value of -1 to indicate that an error occurred. 

ERRORS 

The call fails if: 

CAVEATS 
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DN_READ(3U) 


DNET 


DN_READ(3U) 


NAME 


dn_read - read data from a dnet communication channel 
SYNOPSIS 

int dn_read(channel, buf, nbytes) 

int channel; /* pointer to channel created with dnopen */ 
char *buf; 

int nbytes; /* Maximum number of bytes to read */ 

DESCRIPTION 

The dn_read user library routine allows data to be read from a channel created previously with 
the dn_getclient(3U) or dn_open(3U) library routines. 

SEE ALSO 

dn_write(3U) 

RETURN VALUE 

A positive value representing the number of bytes read will be returned on success. A value of 
-1 will indicate an error. 

ERRORS 

The call fails if: 

[D_SYSERR] A system error has occurred. Check the global variable errno. 
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DN_WRITE(3U) 


DNET 


DN_WRITE(3U) 


NAME 


dnwrite - write data on a dnet communication channel 

SYNOPSIS 

int dn_write(channel, bu nbytes) 
int channel; 
char *buf; 
int nbytes; 

DESCRIPTION 

The dn_write user library routine writes nbytes bytes from buf onto the channel: channel. 

SEE ALSO 

dn_open(3U), dn_getclient(3U), dn_read(3U) 

RETURN VALUE 

A value of 0 will indicate success, and a value of -1 will indicate an error. 

ERRORS 

The call fails if: 

[D_SGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
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1 . DNET Administration Overview 


1.1 Introduction 


Administration of DNET is divided into two general raip.gn ri f5 These 
DNET network issues and 2) local DNET node aHminictra^ 


categories relate to 


1) overall 


1.2 Overall Network Concerns 


The following are the major ’global’ concerns in the administration of DNET. 

1. Adm mims tration of Underlying Networks 

Since DNET operates as a meta-network or a network of networks, its operation is Highly 
dependent on the mtergrity of the underlying networks such as TCP/IP and DECnet. These 
networks are maintained in their ordinary fashion; under normal circumstances so long as the 
underlying network(s) are operational it should be possible for DNET to use these networks) 
for its purposes. The behavior of DNET may be affected by any or all of the following factors; 

1. Changes in Local Operating System 

2. Upgrades or changes in local network interfaces 

2 . DNET Network Map 

The master ’copy 1 of the DNET network map is maintained at - TO BE DETERMINED This 
factor influences, at a minimum, the contents of DNET routing tables. 

3. Consistency of Underlying Network Names in DNET Tables 

4. Routing Strategies in DNET 

Routing tables are currently ’static’. They are loaded when the network is started and are not 
updated while the network is operating. DNET mechanisms could be used to may these tables 
dynamic in the future. 


13 Local Host Administration 

Once DNET software has been installed on a particular computer, administration of the local DNET 
nodegenerally involves the specification of the number and types of DNET application servers which 
will be allowed to operate on the local node, adjustment of quotas and permissions as necessary and 
ad mini stration of the DNET routing tables and mail 
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2. Distribution of DNET Software 


2.1 Modification of target machine database - tbls.db 

sccs_src directory on ’stubb/ as follows: py 01 “ c tUc tb,s db m th <= 

1. cd Sdnet home 

2. cd ../sccs_src 

3. get -e s.tbls.db 

4. locate a convenient entry which is similar to the target machine 

NOT ®! Alternatively, one of the default machine entries, bsd dfk. svsv dfk mm Ary 

^ used duri "« d* pwlmov* operation described below w obtain a’ debt* 

An examples for a UNIX host is shown below: 

IUESN1- NASA GSFC, Greenbdt, MD 
luesnl | envname | ONSUN4B 

luesnl I myname | #mynet myfaost 
luesnl | myname | starnet luesnl 
luesnl j net j #destnet nexthost relay nextprotocol 


luesnl | net jstarnet NULL 
luesnl j net jdnettl dltnlc 
luesnl j net jspanet dltnlc 

luesnl j msinlttcp | dechod 
luesnl j msinlttcp jdrexecd 
luesnl j msinlttcp | dtftpd 
luesnl j msinlttcp j dlogind 

luesnl j msinlttcp | dmalld 
luesnl j msinlttcp j dndd 


NULL 
drelaytdtcp 
drelaytdtcp 
dechod 
drexecd 
dtftpd 
dlogind 


tcp 


1 

1 

1 

1 

1 

3 


luesnl | msinlttcp | dndd dndd 0 3 3 

An example entry for a VAX which is also a DNET gateway machine is shown below: 
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5. 


DFTNIC - NASA GSFC, Greenbelt, MD 
dftnic |envaame|DNDFTNIC 

dftnlc j mynamc | #mynet myfaost 

dftnic | mynamc j spanet dftnlc 

dftnic | mynamc jstarnet dftnk 

dftnic j net |#destnet nexthost relay next protocol 

dftnic | net | spanet NULL NULL dec 

dftnlc | net | dnettl dacvax drelaydtdec 

dftnic | net jstarnet NULL NULL tcp 

dftnic | n ulnltdec | drelaydt drelaydtl 1 I 

dftnlc j nulnl td ec | dechod dechod 1 2 

dftnic j nulnltdec jdrexecd draecd I 1 

dftnic | nulnltdec ( dtftpd dtftpd 1 1 

dftnlc j nulnltdec j dloglnddlagtnd Oil 

dftnlc j nulnltdec | dmaild dmaild 0 1 

dftnlc j nulnltdec jdndd dndd 0 3 

dftnlc jnulnlttcp | drelaytd drelaytd 1 1 


2 

1 

1 

1 

3 

1 


copy this entry to the bottom of the file and change the machine 
pertinent locations. 


name to that of the target in all 


2.2 Creating the distribution files 


S ° ftWarC “ found on mastcr DN ET host, currently dac3b2, 
an AT&T 3B2-600 looted at DAC. A master copy of the DNET software may be obtained at any time 

uTdi f " di “' ibu,ion “ y •-*“ "• “r* *» 


1. login to stubby or dac3b2 

2. cd /mnt/comm/dnet/bin - stubby 


/usr/nasa/dnet/btn - dac3b2 
makemove 


di "* ,0,y /tmp/dntt_more COM*. the 

dnet p tar 

pvc.ptar 

app.ptar 

commoiiepter 

dg.ptar 

ptar.ptar 

postmove 

poatmove.vnu 


Further details on makemove are provided in the DNET Administrative Reference Manual. 


23 Moving DNET Source Files to Target Machine 


The files generated by ’makemove’ and placed in /tmp/dnct move should be 
machine using FTP and/or copy depending on the network(s) involved. 


moved to the target 


Distribution of DNET Software 3 



The target directory for these files will differ depending on the target machine: 
PTAR Directory 

1. UNIX hosts - /tmp/dnet move 

2. VAX hosts - dnethome: [.dnet] where dnet_home is an arbitrary pat h 


2.4 Generating the target files 

2.4.1 UNIX Machines 

1. Transfer the ’ptar* files,’postmove’, and po6tmove.vms to the target machine 

2. cd duel home /bin 

3. postmove -hnXXX duet home 

where 

XXX U name of this local host & 

(or a default name chosen from bsddflt, sysv_dlfc, mvax dfk, or vax dfh) 
dnet^home is an arbitrary path 

2.4.2 VAX Machines 

The procedure for VAX machines differs only slightly from that on UNIX hosts. The following steps 
should be performed: 6 

1. Transfer the ’ptar* files to the target machine and place the files in the dnet home directory 

2 . login to the target machine 

3. cd dnet_home 

4. @po6tmove.vm s 

5. Enter the name of the local machine when prompted 

(or a default name chosen from bsd_dfk, sysv dfk, mvax dfk, or vax dfk) 

6. Wait for postmove to complete unpacking and distributing the files 

2.5 Use of ptar to pack/unpack files 

The ptar program allows the packing/unpacking of files in a generic format for transfer to DNET 
target machines. Ordinarily, postmove automatically extracts files from the ptar files, however this 
extraction may be performed manually, if necessary. 

ptar -x flk.pUr 


2.6 Making the Target Executables for DNET on the local machine 

There are a number of ’make’ files which are included with the DNET distribution package. The 
posfcnove operation automatically places these files in the appropriate directories on the target 
machine and updates the necessary environment variables within the files to the target computer. 
Thus, typically one need only start the ’make’ procedures in order to generate a current copy of the 
DNET executable files. The specific procedures are outlined in the following sections. 
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26.1 UNIX 

1. If this is a first time installation on this UNIX host, follow steps above for setting environment 
variables, etc. 

2. cd $dnet_honw 

3. make 

4. wait for the make process to complete 

26.2 VMS 

1. If this is a first time installation on this VAX, follow steps above for setting environment 
variables, etc. 

2. cd dnethome 

3. The exact nuke file used will depend on the VAX environment as follows: 

1. daevax (or other MicroVAX with VMS and Wollongong TCP/IP Interface) 

make.dv 


2. NASA Vaxes with F .xcc. l an Interface (or other VAX with VMS and TCP/IP 

Interface) ' 

make.dft 

4. Wait for the make procedure to complete 


Distribution of DNET Software 5 



3. Initial Configuration of Local (non-gateway) DNET Node 


This, section describes how to configure a Local DNET node which is not 
considerations for gateway nodes are described in a later section. 


a gateway node. Special 


3.1 Environment & Special Permissions 


3.1.1 General 


Environment Variables/Logical Names 

The following ’environment’ variables are used by all DNET software. 

1. dnethome - the ’home’ directory of the DNET software 
dnet_gateway = 1 if machine is a DNET gateway 
path to dnet bin - the directory containing the DNET 

dnet_debug - this flag controls the generation of various debugging ’log’ files; it should ordinarily 

“ '° 1 ** ** (« DNET 

these general requirements apply to both the UNIX and VMS environments, the specific details 
^nstderably betWeen the operating systems. The specifics are covered in the foUowing 


2 . 

3 . 

4 . 


3.1.2 UNIX 


The environment variables may be set in UNIX by modification of the 
users home directory. 


user .profile file found in each 


Additions to .profile for DNET: 

Bourne shell 

dnet home * / — / _. /dnet; export dnet home 
PATHs existing path specs;/dnet_home/bln 
. $dnet_home/dnIogin.sh 

C shell 


setenv dnethome /_/ _ /dnet 
PATHs existing path specs;/dnet_home/bia 
source Sdnet home/dnloginxsh 
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3.1.3 VMS 


Specification of the DNET ’environment’ is somewhat more complex for VAX/VMS systems. The 

correct operation of DNET requires that certain VMS Privileges and Quotas be set in addition to the 
usual environment variables. 


3. 1.3.1 General Environment Variables - Logical Names 

The general DNET environment variables are set in VMS using The loginxom file in the VAX loom 
ectory should contain the following lines. The entries define logical names in the ’GROUP’ table. 


The values are for the dacvax ma chine 

$ define/group dnethome "$diakl: [s ysthdaei dnct ]" 

$ define/group dnetbin *$disld:[sys0.dneLdneLbin]* 
$ define/group dnet_gateway 1 

For IAF and DFTNIC these definitions should be: 

$ define/group dnet home "cldata: [dnet. dnet] * 

$ define/group dnet bin "ddata:[dnet.dnet.bin]” 

$ define/group dnet_gateway 1 


If the dnet debug option is desired, it should be set in a ’transient’ fashion in the ’JOB’ table as follows: 

$ define/job dnet_debug 1 

Ordinarily, most of the VMS environment can be set ’automatically’ using script files provided with the 
distribution. These scripts are executed as part of the usual ’login’ procedure. Only a short ’machine 
dUU18e Sh ° lJd USUaUy ** requircd “ thc Me. This change is accomplished as 

1. cd sys$login 

2, Edit thc file loginxom to add the following entries: 

$ 

$! DNET Specific Environment 
$ set proc/prlv = grpnam 

$ define/ group dnet home Sdiskl: [sysO.dnetdnet] 

SI run dnetlogin script 
$ @dnet home: dn login. dv 
$ 


NOTE: The specifications for dnet_home & dnlogjn are machine specific, 
for dnet_home for the DAC MicrovaxII, dacvax. 


The example given 


3. The corresponding version of dnloginjcx is dnlogin.dv which is located in the dnet home 

™^ ry ' The CODtents of dnlo «*n.dv are shown below: All dnloginjcx files are included with the 
DNET source code lis tings 
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$! dnlogjaxom 
$! login script for DNET 
$ 

$! logical names 
$ 

$ DNETDEBUG = = *0* 

$ define woolnetlnet Sdiskl: [netwool jietdlstindu dejct l net ] 

$ define wooisys Sdiskl : [ net wool metdlsUncl ude^ys ] 

$ 

$ define/job dnet_pvcdlr Sdiskl: [sys0.dnetdnetpvcdir] 

$ define/job dnet_dgdir Sdiskl: [ aysQ .dneLdne tdgdlr] 

$ deflne/job dnetcommon Sdiskl: [sys0.dneLdneLconimon] 

$ define/job dnetappdir Sdiskl: [sysO.dneLdneLappdir] 

$! deflne/job dnet_debug 1 
$ set proc/priv = grpnam 

$ deflne/group dnethome Sdiskl: [sysO.dnetdnet] 

$ define/group dnetmail Sdiskl: [sys0.dneLdneLmail] 

$ deflne/group dnetj>ln Sdiskl: [sysO.dnetdnet bin] 

$ deflne/group dnet gateway 1 

$ 

$ define c$ include dnet common, dnetpvcdir, dnet dgdir, wool 
woolnetlnet 

$ define vaxcSindude cSindude, sysSlibrary 
$ 

$ assign Sdiskl: [user metlibnetdacnet] TABLES 
S 

S! Clients 
S 

S decho ss "S dnet_bin:dedMtexc* 

S ddecboc = = *S dnet_bin:ddcchocexe* 

S dechon = = *$ dnet hln;dechnn 
$ drexec = = *$ dnet_Mn:drexecexe* 

S dtftp = = *$ dnet_bin:dtftp.exe” 

S dlogfa = = "$ dnet bintdl ogjaese * 

$ dmslrill *a *S dnet b imdmskilLexe* 

S dnetstat * = "S dnet bin:dnetstatexe* 

S dnd * « "S dnet bintdnd.exe* 

$ d m all * = *$ dnet_bin:dmail.exe* 
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»! development only 


i! delmbz = = *$ $disld:[odnet]delmbx*xe' 
> shack * ■ "$ dnet bimshack ta " 

1 l_l®_© = 3 *S duet bind to oxxe” 
bed 3 3 *$ dnet_bln:bc<Lexe* 
ddcchoc = = 1 dnetbln.-ddechoc.exe* 


$ si ■ * 'show logical” 

$ ss * * 'show symbol* 

I Is = = *dir" 

$ 1 ■ * 'dir* 

$ cd = * "set deP 
$ pwd = s 'show deP 
$ vi = = "ed" 

$ view = = "ed/read_only" 

$ ps a s 'show system" 

$ ns = = 'nets tat -a” 

$ more = = ’type/page" 

$ clear = = *@clear* 

$ 

$ II = a ■$ $dlskl:[userjnetilbneLpaul]ll^xe' 

$ ptar a = •$ $dlskl : [ sysO.diiet.bin ] ptar^xe" 

$ od = = •$ $diski : [user jieUiboetpaul] o<Lexe" 
$ wc = = *$ Sdiskl : [ user joetJibnetpaul] wc^xe* 

$ set proc/priv = sysnam 

$ 

$ cd dnethome 
$ cbeckdmail 
$ 


3. 1.3.2 Privileges 


VMS has an extensive set of privileges which control the various operations which a user or process 
may perform on the VAX. The following privileges are required for DNET operation. 

1. SYSNAM 


This privilege is required for DECnet network operations; DNET servers will 
without this privilege 


not operate 


2. GRPNAM 


This allows logical names to be placed in the ’GROUP’ table; This table is 
for the DNET environment variables. 


a convenient location 


3. GROUP 

4. NETMBX 
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Allows creation of ’network* mailboxes 
5. TMPMBX 


Allows creation of ’temporary* mailboxes 


These privileges need to be ’activated’ in order to be used, 
directory should contain the following lines: 

$ set proc/pdv = grpnam 
I set proc/priv = sysnam 


The dnlogtn axx file in the VAX login 


3.1.3.3 Quotas 

XXX "“V of resource controls known as ’quotas’. Certain of these quotas must be 

pertinent quotas is given below. The following section descrL W to dmnge^ le^u^ 

1. Byte Count Limit BYTLM - 60000 


DW5T U ^«'J m T S j the Mora 8' available to DNET for mailboxes. Each active 

tnailboxesforlts oper^oo. MaS * er ^ “■ “"■»> «»>*« a minimum of 2 

Approximate Formula for Determing appropriate Byte Count Limit 

#of Entries in this jnsinit (dec & tep) = AS 

2 • ( DGMS + DMS + AS ) * 2000 
Job Table Quota 

JT Quota - 12000 


This value controls the amount of information which DNET can place in the JOB Table 
3. Paging File Quota - 30,000 


4 . 


This quota is used as an adjunct to swap operations in VMS and 
number of DNET processes increased. 


needs to be increased as the 


AST 


niUDbe ; ° f simulUncous AST operations allowed by DNET; this value will probably 
need to be increased m gateways where a large number of DNET relay processes areiniL. * 

5. Subprocess Quota - PRCLM-30 


TbixQiKM controls the number of subprocemes which may operate under DNET The exact 

“ M,oii “ i *» * x- jj— . values :z 


6. open File Limit - FILLM - 300 


10 DNET ADMINISTRATORS GUIDE 


7. Max Detached Processes - MAXDETACH - 30 


This value controls the number of detached processes which can be started by DNET. This 

quota is important when DNET is started in ’stand-alone’ or detached mode. Value should 
match that of PRCLM. 


3.1.3.4 Setting /Changing Quotas 

The procedure for changing quotas on the VAX is as follows; 

1. Login as ’SYSTEM’ 

2. cd sysSsystem 

3. Run Authorize 

4. UAF> 

modify dnet /prdm =30000 
etc. 

The command show/full dnet may be used to list all of the quotas while in ’AUTHORIZE’ 

3.2 DNET Tables & Local Host ’Service* Files 

Several Files (& Tables) must be modified for the local DNET node. 

1. Network ’Services’ File 

2. Initial Local Version of DNET Routing Table - tbls.net 

3. User Alias Table - tblsjnyname 

4. Master Server Init Table - tblsjnsinittcp and/or thl. msinltdec 

5. Connection Lock Table (for Datagram Backbone Network - not yet implemented) 

Modification of each of these files is discussed below; 

3.21 Services Files 

Service Files on the Local Machine must be modified to support DNET. 

1. UNIX 

The standard file 
/etc/services 

must contain the following entries: 

5279 dms/tcp # DNET PVC Master Server 
5279 dgsudp/udp # DNET UDP Datagram Server 


Initial Configuration of Local (non-gateway) DNET Node 


11 



tSS^£. be d “” fM bj ' ’ r0 °'' -*= “Jy wk«. DNET is firs! Called 


2. VAX/VMS - No special changes are required to register DNET servers on DECnet. 


3.2.2 tbls.myname • Local Host Name (s') file 


found in the dnet - horoe directory contains one or more names for the local host 
Tbs^file allows self-identification’ of the local host by DNET software and is used by the routing 


An example of the , tbls.myname > file is shown below: 


DNET Local ’myname’ Table | 

Name 

Network 

daevax 

span* 

daevax 

dnettl 


3*3 Adding/Deleting/Modifying Servers at a DNET host 

3.3.1 Types of Servers 


There are two application server types defined within DNET: 

L S T W ,: C f Cd by die “ t P rocesses > service providers include a DNET 

Basjf V° package. For all these services (File Transfer, Network Command Server other 
application servers) there is a process which spawns copies of them and assigns the copies to 
clients on request. This controlling process is the "DNET Master Server". 

2. Other Servers (user defined, etc.) - spawned via DNET network command server 

(n !. t i7 C T- Serv) df* server ? do not contain the DNET Basic I/O Package. They depend on the 
network command server to interface with DNET. ? 


3.3.2 Control of Servers 

2LSTEL? Prc? r!kj r T e . rS , which re< l u ‘ rc beaming service is under the control of the DNET 

depe^Pn'di ‘ *?“* SCrVCrS ** Cither P rc spawned or spawned on demand 

depending on the type of host and local system considerations. 

M^ 0naI C °^! Ct i OQl f SS “H*® “ 8,80 arable to these servers if they register with the Datagram 
Master Server. Details of connectionless operations are provided in a later section. 


3.3.3 Number and Types of Servers 

* Pa^tiC,,li, ' DNET h0< “ C0W '° ,S "“” bM “ d *** ° f DNET 
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The number and types of servers are determined by the DNET Master Server Table Init file: 

This is a ’flat’ ASCII file. Entries in the file appear on separate rows and have the format as follows: 



The number of prespawned servers is specified in column 3. 

The Maximum (permissible) number of servers of this type is specified in column 4 
Column 5 contains the number of servers to be started when DNET is first started 
Servers may be added or deleted by editing this file (DNET admin privileges required) 
Further discussion of the significance of these entries is provided in the following sections. 


A separate Master Server Init File is required for each protocol connection at a DNET host Thus, at a 

a Tcp/,p “ d 1 dec - — — ■» - Sts: 


3.3.4 Prespawning of Servers 

niWT^ 0 “ PrOVC J h f cffidcncy of r “Ponse for DNET service requests on VAX machines, certain 
DNET servers may be prespawned’ prior to service requests. 

H P '“ PaW ” e<l “ ****** “ tab Table Fde described 

Possible algorithms for spawning and assignment are: 

L TT“^u. U ^ ber ° f "P'® 5 of ^ according to the contents of the 

NET Master Sorer Init Ifebie keeping their process id’s for later use b forming the process 
names to give to clients. After allocating a server to a client, spawn another to replace it. ? 

^ T^ni^t W Dtly U! * d SCrViCCS * SpaW ” ODty When * *** a «^er. This is the 

3 * r* 4 f™* 5 ' Spawn the maximum number desired and have servers listen 

w a< ?* ? when they complete their service for a client, and at the same time notify the 

Master that they are ready for assignm ent 1 
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3.3*5 Maximum Number of Servers 

p y*“*[* r Mnl f ok maximum number of simultaneous copies of a particular server which are 

^ " *«— — 4 " 


3.3.6 Adding/ Removing Servers 

The following steps are used to control DNET application servers. 

1 tot horoe^ 35 ^ SCrVCr Ini ‘ TabIC (tWsjn8inittc P & /° r tblsjnslnitdec) found in the directory 

2. ScroU to desired row of table and type in the new entry according to the format described below. 

3. Write the table back, overwriting the existing table. 

4. The new version of the Master Server Init Table will be read automatically when the Master 
server is st3iteu« 


3.4 Datagram Service Administration 

3.4.1 Normal Operation 

Under normal drcnmaances, the datagram service retphrea no twice on the part of the system 


3.4.2 The Static Backbone Network 


This feature is currently not implemented in DNET. 

3.4.21 Adding Elements 

3.4.22 Removing Elements 

3.5 DNET Routi ng 

This section describes the operation and control of routing within DNET from the perspective of the 
local system administrator. 

3.5.1 Router Operation 


^paths to hosts “ thc 10041 n f "e direct connections via usual local network mechanisms. For 
paths to hosts m other networks a dynamic router is used. A hierarchical routing table is used to 

foSS , bOSt t0 A a * VC connection ^“cst or a connectionless datagram should be 

forwarded to ’move’ toward the final destination. 


A typical routing table is shown below; 
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DNET Local Rooting Ifcble | 

Destination Net 

Nod (Gateway) Hoat 

Next Process 

Datagram Protocol 

datftl 


- 


Bponet 

deem 

draiaytd 

•V 

stanst 

deem 

dreUytd 

ndp 

Net X 

HostY 

dreUytX 

ndp 

• 

- 

• 

- 






The four columns in the routing table contain the following information 

1. Destination Network 

2. Next Host (in hierarchical path to destination net) 

3. Next DNET Process (always a relay except for last hop) 

4. Local Datagram protocol used to make next hop 

3.5.2 Routing Example 

The route generated for a typical datagram is shown in the following diagram * 


Client CL X 



Server SV X 


In this example client CL X on DNET host D2 wishes to conduct a session with server SV X on 
DNET host T2. 
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The router on host D2 has the following routing table available: 



DNET Local Rooting Ifcble • Host D2 1 

Dcstiaation Net 

Not (Gateway) Host 

No* Process 

Datagram Protocol 

daettl 

NULL 

NULL 


spuct 

dacrax 

draiaytd 

adp 

st arm* 

dacm 

dreUytd 

adp | 

• 

- 

- 

. 

• 

- 

• 

. 

• 

- 


- 

■ 

- 

• 

. 


* 

• 

• 


The router on host D4 has the following routing table available: 


DNET Local Rooting 1U>le - (Gateway) Host D4 1 

Destination Net 

Not (Gateway) Host 

Not Process 


spanet 

NULL 

NULL 

dec 

daettl 

dacTAx 

drdaytd 

adp 

st aim* 

iaf 

delaydt 

dec 

* 

• 

- 

. 

• 

* 

- 

- 

* 


- 

- 


- 

- 

* 


3.5.3 Routing Table Updates 


Initially routing tabic updates will be handled in a manual fashion. Examination of a method for 
next* «xationL PdateS ^ ^ “ a t0pic for further ex Pa“s»on of DNET as discussed in the 


3.5.4 Future Enhancement of Router Operation 

In the future the router may be enhanced to include searching for alternate paths and servers if the 
standard search fails to satisfy the request. The second search could extend into other networks in 
requests for generic servers that need not be executed in a specific network or host. Extended searches 

h^rdwTr^ ^ tlC S J tenUl ! C r ° Udng> load &harin & “ d ba ^P services for use when failures in 
hardware or software reduce the availability of facilities. The entries in the routing table are updated 

by exchange of connectionless datagrams between DNET gateways and individual DNET hosts. ^ 
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4. Gateway Administration 


DNET gateways arc similar to ordinary DNET hosts but, in addition, they have connections to at least 
two underlying network (protocols) supported by DNET. There is a PVC Master Server and a pair of 

'ZJ** rf ^ P rotOCok “ d » • pre-spedfied Z£r ofZct 
SSSuT Table' Y PrOCCSSCS ' ^ ° f ^ httCr k appropriate Master 


4.1 PVC Relays 

relay processes are named according to the Master server with which they are associated and for 
the protocol pair for which they provide conversion service. The general naming convention is 

drelayXYn where 


X U • single letter representing the protocol of the 
associated master server 


Y is a letter representing the protocol to which 
conversion must be made. 


n is the nth instance of this relay; used to provide a unique — 
for the relay server 


Sh l£ra®!l.^ ET TC T ' D f C “f ‘ ““ « i“<““ of a relay aaMdated 

the TCP/IP master server (dmstep) and providing conversion to DECnet is named: 

drelaytdl 

wi ‘ h DECK ‘ — — <*— «> - 

drelaydt_3 


The PVC Master Server Imt Table for a Typical Gateway is shown in the following diagram: 


Gateway Administration 
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DNET Mat* Saw Iait Tbbit 

l>pical Gateway MkUm 

Sarrarl>pa 

IaugxNaau # P. 

•V^nud Max# Iait# 

dacfcod 

dackod 1 

f 3 

dtftpd 

**pd i 

1 1 

drone 

dme 1 

1 x 

dattaid 

dattaid 1 

1 I 

dacld 

daeldl 1 

It 2 

diogiad 

dlocbd 1 

3 1 

(build 

(build 1 

It 1 

dnlaydt 

dixtaydt 1 

It 5 

drebytd 

dnbjrtd 1 

It 5 


4.2 Relay of Datagrams 


Routing of datagrams is accomplished by the Datagram Master Server 
routing information for datagrams is included as the last 


at each DNET node. The 
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5. DNET Start-up on an Individual DNET Host 


Three Administrative ’Script’ Programs are used to control DNET on a local host machine: 

1. dust art 

2. dnstop 

3. dnadmin 


The sequence of operations necessary to ’start’ DNET on a local DNET host is given below 
vary in their details according to the type of machine/operating system. 


The steps 


5.1 UNIX 


1. DNET Software is loaded onto two or more hosts and at least one DNET gateway. 

2. The local Master Server Init Table, Host Alias Table, DNET Routing Table are checked for 
accuracy and edited as necessary 

3. The command script 

dnstart 

OT ^ T l ° 1116 ncccssar y processes on the local host (NOTE: This script is 

M i ”*!* f ° r ** DNET host mac hines.) Once this script is invoked, he 

DNET Master Server Process and the protocol specific DNET datagram servers becomes 
operational as a DNET Well Known Servers. 

4 ST the “ spawns (° r initializes in anticipation of spawning) the servers 

catcd m its Master Server Init Table. This produces the initial set of servers (File Transfer 
Kemote Login, Command Language Processor, etc). * 

5.1.1 Individual Scripts 


“ riP<S “ ** Xn '“ DNET co»PO»«ts 

1. Datagram Service Script - strdgms 

2. PVC Service Script - strpvc 

3. Network Status Service Script - strstat 


5 2 VAX VMS 

1. cd dnet home 

2. @dnstart 

5.21 Individual Scripts 
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1. Datagram Service Script • strdgmsxom 

2. PVC Service Script * strpvcxom 

3. Network Status Service Script • strstatxom 
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6. DNET Shutdown 


DNET shutdown is done by the following; 

L Admin “^tive Server sends a Datagram to each Domain Server requesting that they 
shutdown all activity. This means no further service requests will be processed 3 all active 
processes, as indicated in the Domain Server Table, will be sent ’ABORT" signals 


server 


The Administrative Server may then be terminated, or left in an idle state until the next network 
sian-up. 

NOTE: If the local node is a DNET Gateway, shutdown may adversely affect the operation of DNET. 

6.1 UNIX 

1. cd Sdnet home 

2. cd bin 

3. dnstop 


6.2 VAX -VMS 

1. cd dnet home 
Z @dnstop 

3. Wait for ’stopping messages to complete 
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7. Network Startup 


There is no global activation procedure for DNET Sinn* dnift » „ . 

DNET network 15 dependent on die follo^ u a meta-network, the .Megrity of the 

1 . Required Hosts are Operational 

2 . Underlying Networks are Operational 

3. DNET Processes Operating at all nodes required to reach a particular destination - i e local 

administrators must have activated DNET at each of these nodes ' ’ 

tftlmse conditions are met, DNET should operate, within the limitations of loading on each of the 


The dnetstat function may be used to examine the 
below). 


integrity of the network, if required 


(see section 
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8. Network Administration Operations 


The following administrative operations are possible for the network as a whole. 

— Modify DNET configuration 

— Add/Delete Underlying Networks 

— Add/Delete Local Hosts 

— Examine and Modify Administrative Tables 


8.1 Network Maintenance 

8.1.1 Adding an additional DNET Host Site 

This is a local operation. 

81.2 Deactivating an existing DNET Host Site 

This is a local operation. 

81.3 Adding an additional DNET Network 

1. One or more hosts in new network must have DNET software installed and operational 

2. DNET Gateways) into the new network must be identified, have DNET software install^, and 
be operational 

3. Routing Tables must be updated to include new destination network and appropriate gateway(s) 

81.4 Deactivating an existing DNET Network 

If a network is to be removed from DNET, this can be accomplished by deleting this network from the 
routing tables. 
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9. Testing a DNET Installation 


This section describes the functional testing of DNET operation at a local node. 

1 M^ke Cdit ^ Mastcr Server Init Tables for this node 

Make sure that at least one echo server, dechod, is specified for this node. 

2. Start DNET on the local node following the procedure described in an earlier section. 

l ° contact ^ * oca ^ node following the instructions in the DNET User's 
Gmde. If you are able to n» He echo program, the PVCmrmce is probably 

4. At the shell prompt, type dnetstat. If a short form list of the DNET servers on rhi< • 
printed, most other local DNET functions are probably working normally. 

5. If another node on the local net is operational, try using dnetstat to 'ping- this node by entering 

dnetstat network host -p 


If this operation is successful, 
properly. 


the DNET connectionless service is also probably functioning 
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10. DNET Initial Demonstration Network 


10.1 Network Topology 

The logical arrangement of the initial DNET demonstration network is shown in 

diPoram* 


the following 
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DAC 

3B2 040 



Pilot Network for DNET 


Additional details on these sites is provided in the following table: 
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Ifenative DNET Wide Area Demonstration Sites | 

Site 

Network(s) 

Computers 

DAC 

DECnet, TCP/IP both Ethernet 

MlcroVAX, 3B2, HP, PCs 

NSSDC- GSFC 

DECnet(SPAN) TCP/IP 

a'/V4:Vj:i WtLJl.TOJI.'mMJB* 


i DECnet 


j IPAC - JPL 

TCP/IP i 

Sun 3 


DECnet 

Sun 3, VAX 

STI - Balt 

TCP/IP, DECnet 

Sun, VAX 

IVE - Colo. 

TCP/IP, SPAN 

Sun, VAX 

IVE - GSFC 

TCP/IP, SPAN 

Sun, VAX 


10.2 Information on DNET nodes 

A list of current contacts & other information for each DNET node is listed in the file dnetlnfo which 
is located m the dnethome directory and part of the usual DNET distribution. 


10J Starting up (a subset of) the Demonstration Network 

Suggested Demonstration Network Subset 

1. DAC - brine - (sun386i) - DAC TCP/IP LAN 

2. DAC - daevax (microvax II) - DAC TCP/IP LAN & Dial-up SPANET (DECnet) connection 

3. GSFC - dftnic (vax) - SPANET (DECnet) and Internet (TCP/IP) 

4. GSFC - iuesnl (sun4) - Internet (TCP/IP) 

A . IOgin scssion must ^ maintained with each site for the duration of the demonstration 
DNET, as described here, requires each a login at each site in order to remain ’up’. 

DNET Account information for these machines is given in the file dnetlnfo, found in the dnet home 
directory. 

1. login to brine 

2. enter ’dnstart’ 

3. On a separate terminal login to daevax 

4. Enter the following: 

cd dnethome 

@dnstart 

5. On a separate terminal, login to daevax as ’system’. Then follow the instructions b the section 
below on establishing an asynchronous DECNet connection from daevax to SPANET. 

6 ‘ daCVaX SPANET connection has been started perform the following steps to start up 

DNET on DFTNIC F 
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set hoet dftnic 
login to dftnic 
cd dnethome 
@dnstart 

7. From a separate terminal, login to dacvax, then perform the foUowing steps to connect to iuesnl 
set boot dftnic 

login to dftnic 

telnet iuesnl 

login to iuesnl 

when logged in to iuesnl, enter ’dnstart’ 

To stop DNET, enter 'dnstop’ on UNIX systems and @dnstop on VAX systems. 
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1 1 . Asynchronous DECnet connection from dacvax to SPANET 


The connedion from DAC to the demonstration network shown in the preceding section is currently 

T^ 0110 " 8 DECnC * conncction which mtTbHLually established 
This section describes the procedure for starting/stopping this link. 

11.1 Starting the Link 

Procedure to establish/drop dial-up DECnet link between DACVAX & ’DFTNIC’ at NASA-GSFC. 


Assumptions: 

- Hayes Modem connected to port on VAX 

- Phone line to DAC Switch is connected 

- Md. tie line available on the DAC switch 


1 . 

2 . 

3. 

4. 

5. 

6 . 

7. 

8 . 

9. 

10 . 

11 . 

12 . 

13. 

14. 

15. 


Logon to VAX as ’SYSTEM’ 


set host/dte ttal 


atz[CR] 


If the response is not OK, try following the steps 
link may be hung from an earlier session. 

atdt91,2869000{CR] 


in the shutdown procedure in the next section; 


Wait for connection 


In response to Enter Number: 
type ’iafinppICR]’ 

When ’Call Complete’ msg appears 
[CR][CR] 

In response to ’enter class’ 

type ’dftnic* [CR] 

"typ® [CR][CR] several times, then enter 
user: ASYNCH 


password: enter password here 

wait for message ’DECnet’ control returned 

test by entering ’set host dftnic’; should respond with a username, password 


11.2 Stopping the asynch DECnet link 


Asynchronous DECnet connection from dacvax to SPANET 
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1. login to the dacvax as SYSTEM 

2. Disconnect modem (power switch o$ then on); yes, it’s not pretty, but don’t ask questions! 

3. cd sysSsystem 

4. run ncp 

5. NCP> set circuit tt-O-1 state off 

6. NCP> exit 
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12. DNET Network Utility Commands 


12.1 Examining The Status of DNET 

DNET provides a general network utility function dnetsUt which allows the user to determine a variety 
of information about local or remote DNET nodes. Information which dnetstat can obtain for both 
local and remote nodes includes: 

1. Is DNET ’alive" at the Node? 

2. The Number of active and inactive DNET Processes (long and short formats; Streaming and/or 
Connectionless Options) 

3. Statistics of DNET Use at the Node 

4. DNET Routing Tables at the Node 

The general form of the dnetstat command is as follows: 
dnetstat [dnet network] [dnet host] [options] 

If the network and host arguments are both omitted, the local host is assumed by default. 

If the status of a host on the local DNET network is required, only the dnet host argument is required 
(local network is understood). 

12.2 Testing if DNET is alive 

As an introduction to dnetstat, try using the ’ping 1 option on your local host. This is done by typing 

dnetstat -p 

If DNET is ’ru nnin g* on the local machine, the following message will appear: 

DNET is ALIVE at dnet network dnet host***** 

This response indicates that 

!• At least one DNET PVC Master Server is running on the local node 

2. The DNET Datagram Master Server is running on the local node 
If DNET is not running normally on your system, the following message will appear 

Timed out waiting for response 


Now try using dnetstat to ’ping* another DNET host on the local or a distant DNET network. 

If this is successful, you arc further assured not only is the DNET software running at that host, but 
also that the DNET datagram service is operating (at least between your machine and the distant host). 
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12 J Obtaining Status of DNET Servers 

dnetstat may be used to obtain the status of DNET processes at local and remote DNET nodes. 

This information may be obtained in the following formats 

1. Connection Oriented Services only 

2. Connectionless (Datagram) Services only 

3. Both Services 

4. Short Display Format - types, number avail, and state of servers 

5. Long Format - short format info + (Process IDs) and Start /Idle Tunes 

The short listing of server status is shown below. The command used is: 
dnetstat [network] [host] 

******* DNET VIRTUAL CIRCUIT SERVER STATUS at- dnettl sun3: 


Srv'fype 

Image 

PS 

Av 

Max 

s# 

dmstep 

dechod 

dechod 

1 

i 

1 

1 

drexecd 

drexecd 

1 

i 

1 

1 

dtftpd 

dtftpd 

1 

i 

1 

1 

dndd 

dndd 

3 

3 

3 

3 

dloglnd 

dloglnd 

1 

1 

1 

1 


******* DNET CONNECTIONLESS (Datagram) STATUS at: dnettl sun3: 
ProcName S StartTIme 

dgstep 1 Aug 1 10:44 

1 Aug 1 10:44 

dnstatd 1 Aug 1 10:44 

dnetstat 1 Aug 1 10:46 


A longer listing of the server status may be obtained using the 1 (long) and c (connection) options. 

dnetstat [network] [host] -led 
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****** * DNET VIRTUAL CIRCUIT SERVER STATUS at: dnettl sun3: 


Sit Type 

Image 

PS 

Av 

Max 

S# 

PID 

IU 

St Time 

Idle Since 

dmstep 






5489 


Aug 1 10:44 


dcchod 

dcchod 

1 

1 

1 

1 

5491 

N 


Aug 1 10:44 

drexccd 

drexccd 

1 

1 

1 

1 

5492 

N 


Aug 1 10:44 

dtftpd 

dtftpd 

1 

1 

1 

1 

5493 

N 


Aug 1 10:44 

dndd 

dndd 

3 

3 

3 

3 

5494 

N 


Aug 1 10:44 







5497 

N 


Aug 1 10:44 







5498 

N 


Aug 1 10:44 

diogind 

diogind 

1 

1 

1 

1 

5499 

N 


Aug 1 10:44 


A long listing of the both virtual circuit and datagram server status may be obtained using the 1 (long), 
c (connection), and d (datagram) options. 

dnetstat [network] [host] -led 


******* DNET VIRTUAL CIRCUIT SERVER STATUS ah dnettl sun3: 


Srv Type 

Image 

PS 

Av 

Max 

s# 

PID 

IU 

St Time 

dmstep 






5489 


Aug 1 10:44 

dcchod 

dcchod 

1 

1 

1 

1 

5491 

N 

drexccd 

drexccd 

1 

1 

1 

1 

5492 

N 


dtftpd 

dtftpd 

1 

1 

1 

1 

5493 

N 


dndd 

dndd 

3 

3 

3 

3 

5494 

N 








5497 

N 








5498 

N 


diogind 

diogind 

1 

1 

1 

1 

5499 

N 



******* DNET CONNECTIONLESS (Datagram) STATUS 

at: dnettl sun3: 


ProcName 

s 

PID 

IPC-Name 

IPCID 

SIG 

MSzStartTime 

dgstep 

1 

5482 

DN 5482 

1 

0 

OAug 1 10:44 


1 

5481 

DN5481 

2 

0 

OAug 1 10:44 

dnstatd 

1 

5495 

DN~ 5495 

3 

0 

OAug 1 10:44 

dnetstat 

1 

5504 

DN5504 

4 

0 

OAug 1 10:45 


Idle Since 


Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:44 
Aug 1 10:44 


To obtain the routing table at a particular host, enter the follow ing command: 
dnetstat [network] [host] -r 
An example of output resulting from this command is: 

******* DNET ROUTING TABLE at: dnettl sun3: 


DestNet 

Nxt Host 

Nxt Proc 

DG Protocol 

dnettl 

NULL 

NULL 

tep 

spanet 

daevax 

drelaytd 

tep 

starnet 

daevax 

drelaytd 

tep 
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12^4 Underlying Processes for Network Status 

The dnetstat process is invoked on demand at any DNET host. It provides a set of generalized 
network utility functions. It interacts with the DNET Status Server dnstatd located at either the local 
or any remote DNET node. Its functions are: 

1. Determine status of local/remote DNET processes 

2. Determine/report status (UP/DOWN) of remote DNET nodes 

3. Determine current load of remote DNET processes 

4. Update DNET Routing Tables 

5. Update of DNET Well Known Server Table (if required) 

6. Mai nta i n other DNET status information for use by local processes 

The relationship between the Status Client and a Status Server on one of the DNET hosts is shown in 
the following diagram: 


12.4A Update Local Routing Table 

The hierarchical routing table at a DNET host may be updated through the following procedure: 

1. Poll local DNET Gateway(s) for their routing table 

2. Retrieve the Gateway Routing tables 

3. In turn, poll the more distant gateways to retrieve their routing tables 

4. By deduction, determine local routing table contents 
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13. DNET Errors 


The following errors are defined within DNET. 


#define 

D NOERR 

0 

/• No DNET error •/ 

# define 

D~SYSERR 

1 

/• A system error has occurred •/ 

# define 

DBADSTATE 

2 

/• program in wrong state to Issue this dnet call •/ 

# define 

D BADARG 

3 

/• value of argument was determined to be invalid */ 

#deflne 

DOVRFLW 

4 

/• overflow of i/o buffer */ 

# define 

DAEXIST 

5 

/• The specified object already exists •/ 

#define 

DESRVRSP 

6 

/• Error return value in DGMS service req response */ 

# define 

DEPERM 

7 

/• Permission Denied •/ 

#deflne 

DNOMSG 

8 

/* DNOWATT flag set and no message waiting to be read */ 

# define 

d'nodgrsc 

9 

/• No more available DGMS resources */ 

#deflne 

DINTERN 

10 

/• Internal DNET error •/ 

# define 

D BADNM 

11 

/* Invalid process name was specified */ 

#deflne 

D DGTB 

12 

/• Datagram To Big */ 

# define 

D MSGTB 

13 

/• Message To Big •/ 

#definc 

D BADHN 

14 

/* Could not find net/host combination in router tables */ 

# define 

D ADGENF 

15 

/* ADGUT Entry Not Found •/ 

#deflnc 

D PN2BIG 

16 

/• Process name string too big */ 

# define 

D IPCNM2BIG 17 

/* I PC name string too big. DNET code error V 

#deflne 

D NOEX1ST 

18 

/* The specified object does not exist •/ 

# define 

D INTR 

19 

/* A signal interrupted the library routine */ 

#deflne 

D NOSRSC 

20 

/• Temporarily out of system resources */ 

# define 

D~NODNET 

21 

/* Missing all or part of dnet provider */ 

#define 

D WOULDBLOCK 

22/* Operation would block */ 

# define 

D TIMEOUT 

23 

/* Timeout or retry count exceeded */ 

#deflne 

D~QUOTA 

24 

/* Quota limit exceeded */ 

# define 

D NOSYSFILE 25 

/• DNET system file/table not found */ 

#deflne 

D SYNERR 

26 

/* DNET system file/table syntax error */ 

# define 

D NOIMAGE 

27 

/* (server) not file not found •/ 

#deflne 

D HOMELESS 28 

/* Env variable *dnet_home’ not defined */ 

# define 

DSRVNOACK 29 

/• No respone from application server */ 

#deflne 

D NOHOST 

30 

/* No such host •/ 

# define 

DNOPATH 

31 

/* DNET could not find a path for the sre/dest pair */ 

#define 

D SYSUBERR 32 

/* System library function failed */ 

# define 

dnodnetsrv 

33/* DNET servers dms/dgstep not defined in ’etc/services’* 

# define 

D - SHUTDOWN 34 

/* Orderly shutdown from master server */ 

#deflne 

D MAXERRS 

35 
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•dgmserrmsgs [ DMAXERRS] = { 


static char 

"No DNET error", 

"A system error has occurred*, 

"program in wrong state to issue this duet call", 

"value of argument was determined to be invalid", 

"overflow of i/o buffer", 

"The specified object already exists", 

"Error return value in DGMS service req response", 
'Permission Denied", 

"DNOWAIT flag set and no message waiting to be read", 

"No more available DGMS resources", 

"Internal DNET error", 

"Invalid process name was specified", 

"Datagram To Big”, 

"Message To Big", 

"Could not find net/host combination in router tables", 
"ADGUT Entry Not Found", 

"Process name string too big", 

"IPC name string too big. Probably DNET internal code error", 
"The specified object does not exist", 

"A signal interrupted the library routine", 

"Temporarily out of system resources", 

"Missing all or part of dnet provider”, 

"Operation would block", 

"Timeout or retry count exceeded", 

"Quota limit exceeded", 

"DNET system file/table not found", 

"DNET system file/table syntax error", 

"Image (server) file not found", 

"Env variable ’dnethome’ not defined", 

"No respone from application server", 

"No such host", 

"DNET could not find a path for the sre/dest pair", 

"System library function failed", 

"DNET servers dms/dgstep not defined in ’/etc /services’", 
"Orderly Shutdown from nm^r server" 

}; 
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14. DNET Security 


14.1 Execution Security 

Access to remote DNET hosts is always via the PVC or Datagram Master Servers. Once connected to 
the remote host, the DNET client process will be connected to the corresponding server, if one is 
available. An optional login function may be placed in any of the DNET client-server pairs (currently 
login is required for dlogin and dtftp). See the next section and the DNET Programmer’s GUIDE & 
REFERENCE MANUAL for further information on the use of dn login. 

When DNET provides access to remote execution of processes, the execution privileges for non-DNET 
processes are the same as for a locally-connected user. 


14.2 User Security 

The functions dn_login & dn_l ogin_verify may be used on the client and server DNET applications 
respectively in order to validate user access to the server machine. 

14.21 UNIX 

The /etc/passwd is used by dn_login_verify in the UNIX environment to validate DNET users where 
an application requires such validation. The user login account names and passwords are maintained 
in the normal fashion for the local UNIX system. 

14.22 VMS 

No password protection is currently implemented on VMS systems for DNET other than a very weak, 
’hardwired’ password. 

A more general approach would incorporate a routine to access the uaLdat file in order that user 
passwords could be checked. Attempts to locate and/or write such a routine have been unsucessful to 
date. 

14 3 File Security 

Access to files on individual systems is dependent on the local file protection mechanisms. 

Once a user has been ’validated’ using the dn_login he has the same file access privileges as he would 
have had he ’logged’ on to that host via some other procedure. 
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15. Electronic Mail Administration 


The initial version of DNET mail is quite elementary in concept and requires no maintenance. 

The mail client process dmall interacts with local or remote server processes dmaild and places mail 
in a file with the name of the destination user (account) in the directory dneMiome/mail. 

DNET mail will operate on the local node provided 

1. the dmaild server is operational (has been started by the DNET master server). 

2. the directory dnethome/mail exists - this is ordinarily created by the DNET postmove 
procedure when DNET is installed on a local machine. 

If mail fails to operate, these two conditions should be checked and appropriate action taken as 
needed. 
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16. Library and Program Pool Administration 


Master source code for DNET is m aintain ed under sees on an AT&T 3B2-600 at DAC in the directory 
/usr /nasa /dnet/sccs src. The ’master’ copies all DNET code are maintained in under this top 
directory with the following organization. The ’standard’ DNET directory structure is shown in the 
figure below: 

usr/nasa/dnet/sccssrc/ ~ 

/common /pvedir /dgdlr /appdir 

NOTE: Administration and maintenance of the files in this directory tree is essential for the integrity 
of the DNET code. 

Most co mm on modifications to DNET will likely occur in files in -/sccs_src/ and st Changes to the 
subdirectories ./common, _/dnet/pvcdir, _/dnet/dgdlr should only be undertaken with a view toward 
global fhany in mind. The administrator of these flies should make every effort to ascertain that 
the DNET code at all sites ’in the field’ is consistent with the latest copy maintained under sees and 
vice versa. 
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17. DNET Performance Monitoring 


17.1 General 

There was no performance specification for throughput or system loading for this initial version of 
DNET. Nevertheless, some care was exercised in both the design and implementation of the software 
in an attempt to make the overhead of DNET as low as possible. These efforts were qualitative in 
nature, empirical attempts to make DNET have as ’light 9 an effect as possible on the systems and 
networks involved. 

Despite the absence of a formal DNET performance specification, it seemed useful to provide at least 
some ru dim entary quantitative performance measurements for the system. This section describes the 
measurements made on DNET responsiveness. 

In a distributed, heterogeneous environment, it can be exceedingly difficult to define a ’stable 9 test 
environment for conducting timing tests of any kind. The number of users, number and types of 
processes, and the network communication traffic in the test environment may all be beyond the 
control of the person performing the test. 

At fhk stage of development, it seems most important to comment on how DNET compares with a 
comparable homogeneous network environment under similar conditions. This can be done in the 
DAC portion of the DNET testbed environment. 

17.2 DNET Performance Test Application - dptc 

17.3 VMS Host vs UNIX Host 

17.4 DECnet vs TCP/IP 
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18. Glossary 


The following terms are used in the description of DNET: 

Applications Servers- 

Servers such as File Transfer, Remote Login, Remote Execution, etc that perform 
services for clients. Applications Servers are invoked on demand by clients after using 
the Service Assignment to obtain the name of an available server. 

Connection Lock Ihble- 

List of open connections held by process for use by its Basic Datagram I/O package. 
Locked connections result from user requests for Permanent Virtual Circuits. 

Datagram Master Server (DGMS)- 

A server process, located at each DNET host and gateway, which provides an interface 
to DNET clients and servers and the DNET Connectionless Datagram and Signalling 
Service 

Datagram Protocol Servers (DPS)- 

Protocol specific servers located at each DNET host and gateway, which provides an 
DNET Connectionless an interface to the underlying network Datagram service. 

Master Server Inlt Thble- 

These tables, tbU*msinittcp and tUsjnsinltdec contain initialization information for 
the DNET Master Servers including the type of server to be activated, the maximum # 
allowed at this host, and the number to make available initially, and an indication of 
whether the server must be prespawned. The tables are updated by the local System 
Administrator at the specific DNET host. 

Master Server Ihble- 

One for each DNET host, it contains information on the types and numbers of each 
class of DNET server actively supported on this node at any instant. Each generic 
server entry points to a Server Instance Tfcble which lists the current specific instances 
of a particular class of server. It is updated by the Master Server and by specific 
DNET application servers. 

Master Server Process (DMS)- 

Proc esses, one per Network, mana ging the Master Server Table, handling server 
registration, server assignment, and server control. They are spawned by network 
start-up command files. 


DNET Bask I/O package- 
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I nc luded as library within an application program, it provides network i/o interface 
including datagram formatting. 


Gateway- 


A DNET node at which comm unicat on protoad boundary is passed. DNET relay 
servers move data from one network to another performing an effective protocol 
conversion for streaming services. These servers are created, allocated, and used like 
any other DNET streaming applications servers. The Datagram Master Server, in 
conjunction with protocol specific datagram servers performs a similar function for 
DNET datagrams. 

Network Command Line Interpreter- 

DNET Client process that directs the execution of network commands using 
datagrams sent to various hosts and several servers. 

myname - hostname table- 

A table, tblsjnyname, maintained in the dnet home directory on each DNET node 
lists the DNET networks to which that host is connected and the name(s) by which the 
local host is known on those networks. 


Network Command Language Processor- 

Server that directs the execution of network commands using datagrams sent to various 
hosts and several servers. It is an application server, copies can be pre-spawned or 
spawned on demand. 

Network Command Server- 

Spawned by request from Command Language Processor, this Server is directed by 
Command Language Processor. It spawns processes and directs i/o to execute network 
commands. 

Network Status Server- 

Resides in each network ho6t. Receives Host Status Tables, Host Alias Table, Well 
Known Server Tables, Connectivity Tables, and periodically sends "I am alive" 
messages to the Administrative host. To ensure these periodic messages are sent the 
Bask datagram I/O package uses a timer/wake-up signal to initiate the trans mi ssion 
of the message to the Network Status Client. Because this is done by the I/O package 
and there is a copy of this package in every process that uses network I/O the network 
status data is collected on a per process not per host basis. 


PVC Relay 

A DNET relay used in the completion of DNET Permanent Virtual Circuits (PVCs). 

Relay 

Special DNET application processes located in a DNET gateway which perform 
protocol conversion for DNET streaming sendee between d i s simil a r networks. The 
appropriate Master Server process ’listens’ on a particular protocol boundary when 
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idle and a ssig n s a relay when a request for a protocol h’hop* is received from DNET.. 
The relays are named according to the protocol boundary which they are intended to 
bridge. Thus a T-D relay services requests which arrive on a TCP/IP network, 
relaying data to a DECnet net. Relays operate in a full duplex mode while actually in 
use. 


Router 


DNET employs a hierarchical routing strategy. Each DNET node has, for every 
(DNET) network known to it, information on the next DNET host to contact in order 
to move data toward the destination. The DNET router function uses the information 
in the routing table as follows: Given a destination network, host, and process, returns 
the next ’best’ hop (network, host, process) to ’move’ toward the destination. 


Routing Tfcble- 


A hierarchical routing table that contains the next ’hop’ from the local DNET 
host/network in the direction of all other DNET networks. A minimal version of this 
table is provided with the distribution copy of DNET. The table is currently 
maintained manually by the local system administrator. In the future, this table will be 
dynamically configured and maintained by the local DNET Network Status Server 
after intial startup has taken place. The routing table is named tbls.net and is located 
in the dnethome directory. 

Server Assignment Function- 

Returns the name of an available server to a requesting Router, and updates the 
Domain Server Table. 

Server Instance lhble(s- 

Lists the current specific instances of a particular class of DNET Application Server. 
Entries are made by the Master Server and cleared via dn_done() calls from the 
servers as they complete their tasks. 

Server Registration Fundi on- 

This function is part of the Domain Server Process. It updates the Domain Server 
table with information from Servers (e.g.”now in use"). 
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CHECKDMAIL(l) 


DNET 


CHECKDMAIL(l) 


NAME 


checkdmail - dnet ’mail’ auto-user notification process 
SYNOPSIS 


checkdmail 

DESCRIPTION 


The checkdmail process is invoked by the DNET login script 
host. It checks if a non-null mail file is present in 
(dnet_home:mail for VMS), and if so notifies the user with the 


when a user logs in to a DNET 
the directory dnethome/mail 
message: 


You have DNET mail 


The user may then invoke the dmail client to read this mail file. 

The ability to run checkdmail depends on its presence in the Master Server Init Table for the 


SEE ALSO 

dms, dmail(lD), dmaild(lD) 
RETURN VALUE 

ERRORS 


The call fails if: 
[DDGTBj 



DECHOD(l) 


DNET 


DECHOD(l) 


NAME 


dechod - dnet ’echo’ server 
SYNOPSIS 

Must be entered into the dms init table. 

DESCRIPTION 

““ C °'”'” an ‘ l U " eS S '"' “ “ ! '° m 1 disla, “ DNET d “ b0 Process back 

W ta i r a TaNe by A h DS DNET Se 7 er accordi “* “ **■""**» - the Master 

aerver imt Table. A DNET pernianenl virtual (streaming) connection is opened to the 

inP, “ “ ““ ^ hOM “ ' Ch0 = d ^ f '° m «“ 
° r d — *• ** — 

SEE ALSO 

decho(l), tbls.msinitxxx(4) 

DIAGNOSTICS 

If the dnet_debug environmental variable (logical name in VMS} is defined wifi, , 

va ue, .then a log file will be generated whereerror outpuT m^t Iwed lfThe dnet deh ^ 
value is zero, then all error output will be discarded. dnet_debug 



DLOGIND(l) 


DNET 


DLOGIND(l) 


NAME 

dlogind - dnet ’remote execution’ server 
SYNOPSIS 

dlogind 

DESCRIPTION 

dlogind is the DNET server used to provide remote login function over the DNET network, 
de^tintttn host rUn dePendS ^ ^ presence in the Master Server Init Table for the 

SEE ALSO 

dms, dlogin(l), drexec(l) 

RETURN VALUE 

ERRORS 


The call fails if: 
[DDGTB] 



DMAILD(l) 


DNET 


DMAILD(l) 


NAME 

dmaild - dnet ’mail’ server 
SYNOPSIS 
dmaild 

> DESCRIPTION 

dmaild acts a simple mail transfer server from a remote email client. 

dmaild dependS 0n itS presence in the Master Server tot Table for the 


SEE ALSO 

dms, dmail(lD), checkdmail(l) 

RETURN VALUE 

ERRORS 

The call fails if: 

[DDGTB] 
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DNCLD(l) 


DNET 


DNCLD(l) 


NAME 


dncl - dnet ’network command language’ server 
SYNOPSIS 
dncl 

DESCRIPTION 

The did command invokes the interactive dnet network command language program. This 

the nmTp 3 ° WS ^ p ^ ocessm * of a sln 8 Ie data stream in a distributed environment. To do this, 
p cessing of the data stream is broken into sub command lines SCL (which together make 
up the dncl command line CL). The dncl CL may be entered after the dncl prompt 

dncl> 

The following is a synopsis of the dncl command line: 

SCL > SCL [ > SCL] ... 

You will note that a minimum of two SCL components are required in a CL. The reason for 

the r be h e f P ame< ? whe " we look at the three categories of SCL components. Also note that 
the > symbol is used to delimit the SCL components. 

The following is a synopsis of the SCL component: 

[ [netname::] hostname:] [*]command/file 

Notice that netname and hostname are optional, although if a network name is supplied then a 

a dm!hi me r a S ° , b p SU . PP ‘ ied - In the case where both netname and hostname are specified 
a double colon must delimit the netname and the hostname, and a single colon muTdSS 

C “ m T. d/n,e - F “" hw - if ,he 0>»- val^aSr^ S ,t 

i^dby S Sl,PP a S ° ' hat CO '°" ”' hl ” CO".»«»d/ni, Will be 

If the requested node is the current machine ( the netname and hostname combination 
represent t e current machine), and no colons appear within the command/file value then 

z r k e r n h :r ame :nay omitted - ^ • -dune * - zzsz 

nefwnrk' h . T be 0miUed - ° n dnet gateway machines remember that only one 
network is considered to be current. This means that although the network may be dkectlv 
connected to the current machine, it can not be considered a current network. ^ 

The command/file portion of the SCL represents either a file or a command to be accessed on 
the given machine and falls into one of three categories: 

• First SCL component - must be a file 

• Middle SCL component - must be a command (precede with *) 

• Last SCL component - must be a file 

£ srcfedTp^o 0 ” ,he CL Sy “°f SiS abo,c ’ md ° f *»0 SCL components must 

be specified (a First SCL component and a Last SCL component). This represents the simoles 

rm o a nc and results in a file transfer without filtering. The dncl CLs of greater 
complexity merely represent a higher degree of filtration between the first and la? SCL 

(aTommaS/Th flllratl0n d ® SCnbed here is provided b V the middle SCL component category 
innn??r d i' ^ C ° mmand 15 assumed to read input from a standard location, process^ 
npu received and generate output to a standard location. Many commands can be described in 

XuT clZnd{?^^^ ng/OUtPUt !: , b ? n0t aU WOfk Standard locations input and 
output. Commands that do use standard locations anc work in the input/processing/outDut 

fashion are described as being filters. To work properly as a middle ScL caTegl SCL 

component, the command must also be a filter, as unpredictable results will otheSTcmr 


Page 6 


( 07 / 10 / 89 ) 



DNCLD(l) 


DNET 


DNCLD(l) 


^CL m s^opi C a L b“l eg0ry SCL COmp ° nentS mUSt be preceded ™ th an aster « (*) ^ shown in the 

The UNIX operating system is rich with existing filters to perform a variety of tasks These 
o™ e wTc a L at,Vey rare in the V k MS 0perating syste - Despite this - ^ maybe created 
S„ra VO package 8 “ Pr0g,an,S " S "' 8 “ d S,d ™> «*-* ^ 

SEE ALSO 

dtftp(l), dsh(l) 

RETURN VALUE 

After successful completion of a dncl CL, the following message will be displayed: 

ACKCOMP received. 

ta scr/aittv H ACKC T. P <* CK ”°» W 8' COMPtaion) packet has been initiated by the 
last SCL category driver and has been successfully passed back through all intermediate SCL 

components to be successfully received by the dncl command invoked by the user. 

11!1L A h C h KC 0 ^ P r u CCiVed mC / Sage is not dis P la y ed - ‘hen a cryptic error message will be 
displayed describing the reason for failure. If the error message is preceded by dncld* then this 

“view^ 31 3 P ° SSibly rem ° te n ° de ’ 3nd this messa 8 e was propagated back 

A common form of error message is: 

No route to netname::hostname:dncid 

th3 u thC n ° de specified could not be f ound from the current location. Two things 
should be remembered to help to solve this problem: ^ 

1 h^vebe^uLd^ SPedfed the n ° de nam<5 POrti °“ ° f thC StatCd SCL ’ and the default ma y 

2. The node is always relative to the node on the previous SCL component. The first SCL is 
a ways relative to your current node. As an example, if the first SCL was SDecifed as- 
spanet::iaf:sys$login:myfiIe , and the second SCL was: •sort, then it would tr£ to spawn 
the sort filter on the spanet::iaf node. y P 

CAVEATS 

Never make assumptions about current location within a file system on any node when creating 
CL com p onen ts . Absolute pathnames or logical names must be used for files. For commands 8 
absolute pathnames or logical names must also be used, but on UNIX operating systems the 
H environmental variable may be set by the dnet administrator before the dncl drivers are 
ini la e so that they can be forced to look in non-normal locations for UNIX filters. 
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DNETSTAT(l) 


DNET 


DNETSTAT(l) 


NAME 


dnetstat - obtain dnet network status 
SYNOPSIS 

dnetstat [dnetjietwork] [dnet host] [-acdfhlnprs] 
DESCRIPTION 


The dnetstat command allows the display of various 
Information may be displayed in various forms, depending 
netstat can be used to determine the status of all DNET 
usage statistics. 


DNET-related data structures, 
on the option which is specified, 
servers, routing tables, and server 


Information may be displayed for the local DNET node 
other DNET nodes. 


or may be retrieved and displayed for 


Options: 

nVtwork^L n me W d° rk ^ ^ DNET ^ Which information “ desired; if 

from w “ * — i if M 

If none of the below options is specified, the defaults local _host & [-cd] are assumed 
-a Display all available information (in long format) 

-c Display Status of Connection (Streaming) Servers 
-d Display Status of Datagram (Connectionless) Servers 

between machines with f ° rmat; aUows °P tional conversion 

-h Display help on options for dnetstat 
-I Display other specified options in long or extended format 
•n show DNET map (network, host) 

-P ping the specifed host - i.e. test if DNET ic ai™. ,u .,. . . 

options. If successful, the message: Specif,ed host P ove ™des all other 

DNET is Alive at dnet^network dnet host 

" is — — * wui timeouI 


Timed out waiting for response 


■r show DNET routing tables for the specified node 

•s show per-DNET server statistics (dtftp, drexec, dmail, dncl) 
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DNETSTAT(l) 


DNET 


DNETSTAT(l) 


SEE ALSO 

dnstatd, tbls.msinitdec, tbls.msinitdec, tbls.net 

diagnostics 

The call fails if: 

Specified host is not up 

DNET is not operating on the specified host 

dnstatd is not operating on the specified host 

In each of the above instances, dnetstat, will report: 

Timed out waiting for response 
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DNLOGIN.CSH(8) 


DNET 


DNLOGIN.CSH(8) 


NAME 


dnlogin.csh - DNET logir script for UNIX systems with ’C SheU 
SYNOPSIS 


©dnlogin.csh 

DESCRIPTION 


UNlv" 108 / 11 CSh SCr,pt T S Up the °P eratin 8 environment for DNET when a user loes in m a 
the user’s lo^nTrectory. A hstinglf thticript 'follows: the fUe pr ° li,e b 


# dnlogin.csh 

# login script for C Shell under UNIX for DNET 

# First set dnet_home in your .login, 

# Then source this file. 

setenv PATH "$PATH":$dnet_home/bin 
checkdmail 
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DNLOGIN.DFT(8) 


DNET 


DNLOGIN.DFT(8) 


NAME 

dnlogin.dft - DNET login script for NASA-GSFC DFTNIC VAX 
SYNOPSIS 

©dnlogin.dft 

DESCRIPTION 

SCflPt SC ! / UP the °P eratin 8 environment for DNET when 
,?w, l ^ rUn " ,n8 VMS ' d " l °* indf ' is ordinarily invoked from the t 

user slogm directory A listing of the script follows: 


$! dnlogin.dft 

$! login script for DNET for dftnic 

$ 

$! logical names 
$ 

$ DNETDEBUG = = »o» 

$ 

$ define/job dnetpvcdir $ddata:[dnet.dnet.pvcdir] 

S defme/job dnet dgdir $cldata:[dnet.dnet.dgdir] 

$ define/job dnet common $cldata:[dnet.dnet.comman] 

«, d f f i nC/ / 0b dnet - a PP dir Scldata: [dnet.dnet.appdirl 
$! define/job dnetdebug 1 1 

$ set proc/priv=grpnam 
$ define/group dnet home $cldata:[dnet.dnet] 

« de J“ e / grou P dnet_bin $cldata:[dnet.dnet.bin] 

® define/group dnetgateway 1 

$ 

$ ptar B a »$ cldata: [dnet.bin] ptar.exe" 

S 

$ define conclude dnet common, dnet pvcdir, dnet dgdir, exos etc 
$ define vaxc$include c$include, sys$iibrary 

$! Clients 
$ 

$ decho = = "$ dnet_bin:decho.exe" 

$ ddechoc = = "$ dnet_bin:ddechoc.exe" 

$ dechon = = "$ dnetbinrdechon.exe" 

$ drexec = = "$ dnet_bin:drexec.exe" 

$ dtftp = = "$ dnet_bin:dtftp.exe" 

$ dlogin — = "$ dnet_binrdlogin.exe" 

$ dmskill = = "$ dnet_bin:dmskill.exe" 

$ dnetstat = = "$ dnet_bin:dnetstat.exe" 

$ dncl = — dnet_binidncl.exe" 

$ dmail = = "$ dnet_bin:dmail.exe" 


user logs in to the 
ile login.com in the 
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DNLOGIN.DFT(8) 


DNET 


DNL0GIN.DFT(8) 


$ 

$! development only 

$ 

$! delmbx = = »$ $diskl:[odnet]delmbx.exe" 
$ shack = = "$ dnet_liin:shack.exe" 

5 “ = "$ dnet_oin:i to o.exe" 

$ bed — = "$ dnet_bin:bcd.exe" 

$ ddechoc S dnet binzddechoc exe" 

$ 

$! aliases 

$ 

$ si = = "show logical" 

$ ss = = "show symbol" 

$ Is = = "dir" 

$ I = = "dir" 

$ cd = = "set del" 

$ pwd = = "show del” 

$ vi = = "ed" 

$ view = = "ed/read_ jnly" 

$ ps = = "show system" 

$ ns = = "netstat -a" 

$ more = = "type/paj.e" 

$ clear = = "(©clear" 


set proc/ pri v = sysnam 

cd dnet_home 
checkdmail 
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DNL0GIN.DV(8) 


DNET 


DNLOGIN.DV(8) 


NAME 


dnlogm.dv - DNET login script for DAC Microvax II 
SYNOPSIS 


@dnlogin.dv 

DESCRIPTION 


The dnlogin.dv script sets up the operating environment for DNET when a 
VAX running VMS dnlogm.dv is ordinarily invoked from the file login.com 
directory. A listing of the script follows: 8 


51 dnlogin.com 

$• log'*> script for DNET for dftnic 
$ 

$! logical names 
$ 

$ DNET DEBUG = = "0" 

$ 

$ define/job dnetpvcdir $cldata:[dnet.dnet.pvcdir] 

$ define/job dnet_dgdir $cldata:[dnet.dnet.dgdir] 

$ define/job dnetcommon $cldata:[dnet.dnet.common] 

5 define/job dnetappdir $cldata;[dnet.dnet.appdir] 

$1 define/job dnetdebug 1 

$ set proc/priv = grpnam 

$ define/group dnet home $cldata:[dnet.dnet] 

$ define/group dnetbin Scldata: [dnet.dnet.bin] 

$ define/group dnetgateway 1 
$ 

$ ptar = = "$ cldata: dnet.bin] ptar.exe" 

$ 

$ define cSinclude dnet common, dnet_pvcdir, dnet_dgdir, exos etc 
5 define vaxc$includt cSinclude, sys$library 


$! Clients 
$ 

$ decho = = "$ dnet_bin: decho.exe" 

$ ddechoc = = "$ dnet_binrddechoc.exe" 
$ dechon = = dnet_bin:dechon.exe" 

$ drexec = - dnet_bin:drexec.exe" 

$ dtftp = = "$ dnet_bin:dtftp.exe H 
$ dlogin = = w $ dnet_bin:d!ogin,exe" 

$ dmskill = = "$ dnet bin:dmskilI.exe M 
$ dnetstat = = H $ dnet_bJn:dnetstat.exe" 

$ dnci = = "$ dnet_bin:dncl.exe" 

$ dmail = = "$ dnet_bin rdmail.exe" 


user logs in to a 
in the user's login 
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DNLOGIN.DV(8) 


DNET 


DNLOGIN.DV(8) 


$! development only 

$ 

$! delmbx = = "$ $d,skl:[odnet]delmbx.exe" 
$ shack = = "$ dnet_bin:shack.exe" 

$ L to _o = = "S dnet_ jin:i to o.exe" 

$ bed = = "$ dnet_bir:bcd.exe" 

$ ddechoc = = ’’$ dne: bin:ddechoc exe" 

$ 

$! aliases 

$ 

$ si = = "show logical" 

$ ss = = "show symbol" 

$ Is = = "dir" 

$ 1 = = »dir" 

S cd = = "set deF 
$ pwd = = "show deF 
$ vi = = "ed" 

$ view = = "ed/read only" 

$ ps = = "show system" 

$ ns = = "netstat -a" 

$ more = * "type/page" 

$ clear = = "@clear" 


set proc/priv = sysn am 

cd dnet_home 
checkdmail 
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DNL0GIN.SH(8) 


DNET 


DNLOGIN.SH(8) 


NAME 


dnlogin.sh - DNET login script for UNIX systems with Bourne Shell 
SYNOPSIS 


@dnlogin.sh 

DESCRIPTION 


uwrv n,08in ‘ Sh SCnpt SCtS Up the °P eratix, g environment for DNET when a user Iocs in tn a 
in the uSsTog“| invoked from the fiIe •prolile 


# dnlogin.sh 

# login script for Bourne shell under UNIX for DNET 

# First set dnet_home in your .profile. 

# Then . this file. 

PATH-$PATH:$dnet home/bin 

export PATH 
checkdmail 
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DNSTART(8) 


DNET 


DNSTART(8) 


NAME 

dnstart - start local DNET node 
SYNOPSIS 
dnstart 

DESCRIPTION 

COmmand all0WS the system adm ‘n>strator on a UNIX host to start-up the local 


SEE ALSO 

dnstart. com(8), dnstop(8), dnstop.com (8), startdgms 
DIAGNOSTICS 


The dnstart module is a UNIX shell script. The output directly from the script merely informs 
the user of the modules being started up. Output from those modules may dso appear on the 
screen. The script in turn calls the startdgms to start the DNET datagram service. 


The dnstart script is listed below: 


dnstop 

dnet^homes'echo "${dnet_lroiiie}/" | tr *s */’ */* 

dnetjog = Vtmp/dnet/ M ;export dnet log 

rm -rf /tmp/dnet 

mkdir /tmp/dnet 

ipcrm -Q 100 

cd $dnet_home/bin 

startdgms 

sleep 2 

ech0 -**********.***.******* starting dmst 
dmstcp & 

sleep 1 

echo ’***********************starting dnstatd*** 
dnstatd & 

pidlist = Spidlist" "$! 

echo Spidlist >> "${dnet_home}pidlist" 
sleep 5 

ech0 -*****..*«*,**,**,*,.*, dnet now running . 
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DNSTART.COM(8) 


DNET 


DNSTART.COM(8) 


NAME 


dnstart.com - start local DNET node (on VAX systems) 

SYNOPSIS 

@dnstart 

DESCRIPTION 

local I)NET nock C ° mmand all ° WS administrator on a UNIX host to start-up the 


SEE ALSO 

dnstart(8), dnstop(8), dnstop.com(8), strdgms.com, strstat.com 
DIAGNOSTICS 


The dnstart.com file is a VMS DCL shell script. The output directly from the scrim merelv 

onThe S s^een Se Th f thC m ° duleS bemg started U P- ° ut P ut {rom ^ose modules may also appeal 

datagram m tU [° Ca ^ ^ stf dgnis.coin and strstat.com to start the DNET 

atagram service and the network status server respectively. 


The dnstart.com script is listed below: 
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DNSTART.COM(8) 


DNET 


DNSTART.COM(8) 


$ 

$ cd dnethome 

$ 

$ @dnstop 
$ 

$ write sysSoutput "deleting old log files" 

$ del ’".log;* 

$ write sysSoutput "purging dnet home" 

$ purge 
$ 

$ cd [.bin] 

$ 

$ write sysSoutput "purging dnet home" 

$ purge 

$ cd dnet_home 
$ 

$ write sysSoutput "starting dnet DGMS ..." 

$ @strdgms 

$ 

$ wait 00:00:05.00 
@strpvc 

wait 00:00:05.00 
@strstat 

cd dnet home 

wait 00:00:05.00 

write sysSoutput "DNET Successfully STARTED 
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DNSTART.DET(8) 


DNET 


DNSTART.DET(8) 


NAME 


dnstart.det ■ start local DNET node (on VAX systems) in a detached mode 
SYNOPSIS 


@dnstart.det 

DESCRIPTION 




SEE ALSO 

dnstart(8), dnstop(8), dnstop.com(8), strdgms.com, strstat.com 
DIAGNOSTICS 


as rs 

datagram service and the network status serve, re?“y s,rst “* c ""> ■» «« the DNET 


The dnstart.det script is listed bf low: 


S ! dnstart.det - start DNET in detached mode 
$ 

$ cd dnet_home 
$ 

$ ! stop any existing DNET processes 
$ @dnstop 
$ 


$ cd [.bin] 

$ 

$ set proc/priv=grpnam 

$ define/ group dnet_home "$diskl:[sys0.dnet.dnet]" 

$ define/group dnetbin "$dlskl:[sys0.dnet.dnet.bin]" 

$ define/group dnet gateway 1 

$ 

$ write sys$output 'starting dgms ...DETACHED" 

$ nm/7il n h = h/ 0 ? ; dn ^- home:d 8 m s.log/process = dgms/nowalt - 
run/detached/nodebug/bafferjimit = 60000/subprocess limit=30/io buffered=20 - 
/maximum_working_set = 1024/extent = 1024/working sel = 512/queue Hmit= 30 

/astjimit=30/fiiejimit=200/job_table_quota = 1200/page file =30000 . 

^/privileges = (grpnam,sysnam,netmbx,tmpmbx)/proc=dgms~dgms 

$ write sys$output "starting dgsudpjn ...DETACHED" 

J ^n/demched/nodebng/bnirerJlmitndOOOO/snbprocess limit=30/lo bnlTered=20 . 
/maximum_working_set = 1024/ex,ent= 1024/working set=512/qu^*~linM=30 . 
/ast limit -30/file limit =200/job_table_quota = 1200/page file=30000 - 
^/privileges - (grpnam,netmbx,tmpmbx)/proc = dgsudpjn cgsudp in 

$ write sys$output "starting dgsudp out ...DETACHED" 

$ run / d ^ached/nodebug/bufferjimit=60000/subprocessjimit=30/io_buffered=20 - 
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DNSTART.DET(8) 


DNET 


DNSTART.DET(8) 


firrKSfTr- = 1024 / extent = 1024/worklng set = 512/queue limit =30 

/astjimit-30/file_limit=200/job_table_quota = 1200/page file = 30000 - 

^/privileges = (grpnam,netmbx,tmpmbx)/proc = dgsudpout dgsudpout 
$ write sysSoutput "starting dgsdec ...DETACHED" 

$ run/detached/nodebug/buffer_Jimit = 60000/subprocess limit=30/io buffered = 
/maximumworkingset = 1024/extent = 1024/working sef= 512/queue"limit = 30 . 

/ast limit =30/file limit =200/job_table_quota = 1200/pagt file =30000 - 
/privileges = (grpnam,sysnam,netmbx,tmpmbx)/proc = dgsdec dgsdec 

$ wait 00:00:05.00 
$ 

$ write sysSoutput "starting dmsdec ...DETACHED" 

$ run/detached/buffer_limit = 60000/subprocess_limit=30/io buffered = 20 - 
/maximum_working_set= 1024/extent = 1024/working set = 512/queue !imit=30 - 
/ast limit = 30/file limit = 200/job_table quota = 120o7page Hie =30000 - 
/privileges = (sysnam,netmbx,tmpmbx)/proc = dmsdec dmsdec 

$ write sysSoutput "starting dmstcp ...DETACHED" 

$ run/detached/buffer limit = 60000/subprocess limit=30/lo buffered = 20- 
/maximum_working_set=1024/extent = 1024/working set = 5l2/queue limit = 30 - 
/astjimit=30/file_limit = 200/job_table_quota = 12000/page file = 30000 - 
/privileges = (sysnam,netmbx,tmpmbx)/proc = dmstcp dmstcp 

wait 00:00:05.00 

write sysSoutput "starting dnstatd ...DETACHED" 

run/detached/buffer_limit= 60000/subprocess limit=30/io buffered=20 - 
/maximum_working_set= 1024/extent = 1024/working set = 512/queue limit=30 - 
/astllmit = 30/file_limit = 200/job_table_quota = 12000/pa t ;e_file=30000 - 
/privileges = (sysnam,netmbx,tmpmbx)/proc = dnstatd dnstatd 
S cd dnet_home 
$ 


20 - 
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DNSTATD(l) 


DNET 


DNSTATD(l) 


NAME 


dnstatd - DNET network status server 
SYNOPSIS 


dnstatd 

DESCRIPTION 


° f DNET-related data 

specified, dnstatd can be used to determine the status o ”ll DNET s"® °” T‘ on , which u 
server usage statistics. DNET servers - routln g tabl es, and 


Information may be displayed for the local DNET node 
other DNET nodes. 


or may be retrieved and 


displayed for 


Options: 

° f tht ° NET lM fr °“ » desired; if 

fr °” — “ desired; if both 

If none of the below options is specified, the defaults locaI_host & [-cd] are assumed 
-a Display all available information (in long format) 

-c Display Status of Connection (Streaming) Servers 
-d Display Status of Datagram (Connectionless) Servers 

between machines with differenN^ f ° rmat; aU ° WS ° ptional conversion 

•h Display help on options for dnetstat 
-I Display other specified options in long or extended format 
■n show DNET map (network, host) 

if DNET is alive on ,he specified hosi p “ ■“ — 

DNET is Alive at dnetnetwork dnethost 

E 

Timed out waiting for response 


-r show DNET routing tables for the specified node 

-s show per-DNET server statistics (dtftp, drexec, dmail, dncl) 
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DNET 


DNSTATD(l) 


SEE ALSO 

dnstatd, tbls.msinitdec, tbls.msinitdec, tbls.net 

RETURN VALUE 

ERRORS 

The call fails if: 

Specified host is not up 

DNET is not operating on the specified host 

dnstatd is not operating on the specified host 

In each of the above instances, dnetstat, will report: 
Timed out waiting for response 
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DNSTOP(8) 


DNET 


DNSTOP(8) 


NAME 

dnstop - stop the local DNET services 
SYNOPSIS 
dnstop 

DESCRIPTION 

The dnstop command allows the system administrator to stop the local DNET 

SEE ALSO 

dnstart(8) 

DIAGNOSTICS 

The contents of dnstop are listed below: 

echo ’**********stopping TCP Master Server ***********. 

dmskill tcp 

stopdgms 


services. 
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DTFTPD(l) 


DNET 


DTFTPD(l) 


NAME 

dtftpd - dnet trivial file transfer server 
SYNOPSIS 
dtftpd 

DESCRIPTION 


The dtftpd is the DNET file transfer server, 
remote DNET machines. 


It provides for the transfer of files to and from 


SEE ALSO 

dms, dtftp(l) 
RETURN VALUE 


ERRORS 

The call fails if: 
[DDGTB] 
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MAKEMOVE(8) 


DNET 


MAKEMOVE(8) 


NAME 

makemove - generate a generic image of the DNET source files for transport to a remote 
machine 

SYNOPSIS 

makemove 

DESCRIPTION 

The makemove command allows the system administrator at the Master DNET node to 
generate ’ptar’ files of the DNET source code for transport to remote locations. 

SEE ALSO 

ptar(l) 

DIAGNOSTICS 
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POSTMOVE(8) 


DNET 


POSTMOVE(8) 


NAME 


postmove - generate DNET on a target machine 
SYNOPSIS 

postmove [-m] [-s] [-sc] i-h] 

DESCRIPTION 

The postmove command generates the DNET source and/or executables on a target DNET 
host. 6 

' m make DNET after source code has been unpacked 

' sc suppress cleanup - do not remove local copies of ’ptar’ files after executables 

have been made 

•s create shell environment 

-h help 

SEE ALSO 

makemove(8), sdenv(l), ptar(l) 

DIAGNOSTICS 

The postmove utility is i shell program (or DCL script). Short messages will be generated 
during normal operation informing the user what portion of the postmove is being performed 
currently. Most error conditions result in an abort with the message indicating that an abort is 
taking place. A final message will be issued when the postmove has run successfully. 
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PTAR(l) 


DNET 


PTAR(l) 


NAME 

ptar - pack/unpack file(s) in a generic tar format 
SYNOPSIS 

ptae [-xct] filename 
DESCRIPTION 

The ptar command packs or unpacks a file or files into a generic ’tar’ format for shipment to 
remove DNET target machines. 

-x extract files 

-c Create a ptar file 

•t Table cf contents on existing ptar file 

SEE ALSO 

makemove(8), postmove(8) 

DIAGNOSTICS 

The ptar displays a list of file names as they are being extracted or archived. 
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STARTDGMS(8) 


DNET 


STARTDGMS(8) 


NAME 


startdgms - start local DNET Datagram Service 
SYNOPSIS 


startdgms 

DESCRIPTION 


nNP?J d r COmmand allows the s > stem administrator on a UNIX host to start-up the local 
DNET Datagram service, startdgms is ordinarily invoked automatically by the dnstart script. 

SEE ALSO 


dnstart(8), startdgms 
DIAGNOSTICS 


The startdgms script is listed below: 
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STARTDGMS(8) 


DNET 


STARTDGMS(8) 


if [ "Sdnethome" = "" ] 
then 

echo ’ ’dnethome not set...Aborting 
exit 1 
fi 

dnet_home = ‘echo "${dnet_home}/" | tr-s’/’ ’/“ 
dnetlog = "/ tm P/dnet/";export dnetlog 
nohup dgms > "${dnet_log}dgms.Iog" 2>&1 & 
pidlist=$! 

odgms = "${dnet_log}dgms.log"; export odgms 
sleep 1 

nohup dgsudp in > "${dnet_log} dgsudp in.log" 2>&1 & 
pidlist = Spidlist" "$! 

odgsin = ”${dnet_log}dgsudp_in.log";export odgsin 
nohup dgsudp out > "${dnet_log}dgsudp out.log" 2>&1 & 
pidlist = Spidlist" "$! 

odgsout = "${dnet_log}dgsuc'p_out.log";export odgsout 
sleep 1 

echo '***********************dftms.\og* m ****** ***** ***** ******* **> 
cat $odgms 

echo ’*********************** dgstcp in.log*************************. 

cat Sodgsin 

echo ’***********************dgstcp out.log*************************» 
cat Sodgsout 

# nohup pingerd > "${dnet_log}pingerd.log" 2>&I & 

# pidlist =$pidlist" "$! 

# opingerd = "$ { dnet_log } pingerd.log";export opingerd 

# nohup a be > "${dnet_log}abc.log" 2>&1 & 

# pidlist = $pidlist" "$! 

# oabc="${dnet_log}abc.log";export oabc 

# sleep 1 

#echo ’************************pjNGERD.log*********»*************« 

# cat Sopingerd 

# echo , **** # ** ,|tJ, ‘***** ,> ** ,> ******ABCIog**^* <, *********************» 

# cat $oabc 

echo Spidiist > "${dnet Jiome} pidlist" 
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STRDGMS.COM(8) 


DNET 


STRDGMS.COM(8) 


NAME 

strdgms.com - stsrt local DNET node (on VAX systems) 

SYNOPSIS 

@strdgms 

DESCRIPTION 

nN^ r ? mS ' C ° m command aHows the s y st em administrator on a UNIX host to start-up the 
DNET datagram service Ordinarily, this script is executed automatically by the dnstart.com 

SEE ALSO 

dnstart(8), dnstop(8), dnstop.com(8), strdgms.com, strsta..com 

DIAGNOSTICS 

The strdgms.com script is listed below: 


$ ! strdgms • start DNET Datagram Service 
$ 

$ cd dnet_home 
$ cd [.bin] 


$ set proc/priv= sysnam 

$ spawn/in = nl./out = dnet l.omerdgms.log/process = dgms/nowait run/nodebug dgms 
$ set proc/priv=nosysnam * 8 

$ spawn/in = nl:/out=dnet 
$ spawn/in = nl:/out = dnet~ 

$ set proc/priv= sysnam 
$ spawn/in = nl:/out = dnet 1 
$! set proc/priv = nosysnam 
$! spawn/in = nl:/out=dnet 
$! spawn/in = nl:/out = dnet 
$ 


1 ime:dgsudp_in.log/process = dgsudp_in/nowait run/nodebug dgsudp in 
ome:dgsudp_out.log/process = dgsudpout/nowait run/nodebug dgsudp out 

_home:dgsdec.Jog/process=dgsdtc/nowait run/nodebug dgsdec 

n 

home:pingerd.log/process = pingerd/nowait run/nodebug pingerd 
home:abc.log/process = abc/nowait run/nodebug abc 


$ cd dnethome 
$ 

$ type dgms.log 
$ type dgsudp_in.log 
$ type dgsudp_out.log 
$! type pingerd.log 
$! type abc.Iog 
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DNET 


DNSTOP.COM(8) 


NAME 


dnstop.com - stop the local DNET services on VAX syste ns 
SYNOPSIS 

@dnstop 

DESCRIPTION 

The dnstop command allows the system administrator to stop the local DNET services. 

SEE ALSO 

dnstart.com(8) 

DIAGNOSTICS 

The contents of dnstop.com are listed below: 

$ 

$ cd dnet_home 
$ 

$ write sys$output "stopping dgms * 

$ @stpdgms 

$ write sys$output "stopping dmsdec " 

$ stop dmsdec 

$ write sysSoutput "stopping dmstcp " 

$ stop dmstcp 

$ write sys$output "stopping dnstatd 
$ stop dnstatd 
$ 

$ cd dnet_home 
$ 

$ wait 00:00:05.00 
$ 

$ write sys$output "DNET is halted " 

$ 
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STOPDGMS(8) 


DNET 


STOPDGMS(8) 


NAME 


stopdmgs - stop the local DNET datagram service on a UNIX system 
SYNOPSIS 

stopdgms 

DESCRIPTION 

The stopdgms command allows the system administrator to stop the local DNET services. 
SEE ALSO 

dnstart(8), dnstop(8), startdgms(8) 

DIAGNOSTICS 

The contents of stopdgms are listed below: 

if [ "$dnet_home" = ™) 
then 

echo ’ ’dnethome not set...Aborting 
exit 1 
fi 

dnet_home = ‘echo "${dnet_home}/" | tr -s ’/’ ’/« 

if [ -f "${dnet_home}pidlist" ] 

then 

echo Cleaning up dgms 

else 

echo No dgms running 
exit 0 
fi 

pidlist = ‘cat "$ {dnethome } >idlist"‘ 
echo kill -9 "Spidlist" 
for pid in Spidlist 
do 

kill -9 $pid 
done 

ipcrm -Q 101 

rm "${dnet_home}pidllst" 
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STRPVC.COM(8) 


DNET 


STRPVC.C0M(8) 


NAME 

strpvc.com - start local DNET node PVC service on a system 
SYNOPSIS 

@strpvc 

DESCRIPTION 

The strpvc.com command allows the system administrator on a UNIX host to start-up the local 
DNET node, ordinarily run via dnstart.com. 

SEE ALSO 

dnstart(8), dnstop(8), dnstop.com(8), strdgms.com, strstat.com 
DIAGNOSTICS 

The strpvc.com script is listed below: 


$ ! strpvc - start DNET PVC Service 
$ 

$ cd dnet home 
$ cd [.bin] 

$ 

$ set proc/priv = sysnam 
$ write sysSoutput "starting dmsdec ..." 
$ run/proc = dmsdec dmsdec 
$ write sys$output "starting dmstep ..." 
$ run/proc = dmstep dmstep 
$ 

$ cd dnet_home 
$ 
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STRSTAT.COM(8) 


DNET 


STRSTAT.COM(8) 


NAME 

strstat.com - start local DNET network status server (on VAX systems) 

SYNOPSIS 

@strstat 

DESCRIPTION 

The strstat.com command allows the system administrator on a UNIX host to start-up the local 
DNET node. Ordinarily run by dnstart.com. 

SEE ALSO 

dnstart(8), dnstop(8), dnstop.com(8), slrdgms.com, strsta..com 

DIAGNOSTICS 

The strstat.com script is listed below: 


$ ! strstat - start DNET status daemon 
$ 

$ cd dnet_home 
$ cd [.bin] 

$ 

$ write sys$output "starting dnstatd ..." 
$ run/proc = dnstatd dnstatd 
$ 

$ cd dnet_home 
$ 
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1 . DNET Overview 


make up DNET are descXe^as are som^oTthe^mrtTnt 115 ° f DNET ' ThC Vari ° US elements which 
these elements is discussed in more detail in a subsequent chapter^' 0115 made “ ^ Each ° f 


1.1 Underlying Assumptions 


Pr0t0C0k '° be e " p,0yed “ ,he Unk/Physica, layer for ,h. 

2 ' «SSHe,^S" amP0 " & " e,WOrk ' ayerS> «» “““■ - aU nodes which 

3 ' D°NE*'r ° f 0PCra “ ng SySKm K "” e,S •* "*** » implementation/use of 
4. Initial Operating Environment 

- TCP/IP 

- DECNET 


1.2 Basic Design Philosophy 


DNET communications and computing services are nrmri^A • 

servers. Using the communications services adminish-ahv m environment based on clients and 
processes; clients then request connections to the serve e Processes request the initiation of server 
mode operations are supported The interface to the ^ ^ services ‘ Intera ctive and batch 

h.p»,/ou tput auhroofioJL, b ' a « «* 

A, connection establishntem 

•he .oca, operating syatent. Servers statL SSEXS? 

protocol gateways are 

protocol. Gateways allow programs operating on hosts C USCS 3 cb ® erent communications 

others without concern about possible 8 netw l, ° D dlffe [ ent netw ork t0 communicate with 
acknowlegements for reliabihty and attomitic S? P /° dafcre “ Using end-to-end 
provides protocol transparent, reliable data stit&mTor d 8 f eWayS for P rotoco1 conversion DNET 
connected DECnet, TCP/IP, (and Asynchronous) networks. tranSnmsion between hosts on 

* 2* «* - ^ 

possibly in another network. The path established conmr ^T l ° an ° ther P roc ess in another host, 
dedicated exclusively to the stream mode transport of Tt prOCe “ CS and network connections 
Permanent virtual circuits reduce the number of network ^ b f. tWCe “ the end P oilUs of the circuit, 
associated task initiation required. This significantly imnm T be established and the 

transmitted in a "streaming" fashion in one^ession ? r " C ° rk P erforman ce. When data is 
initial cost of circuit establishment. ^ SCSS1 ° n tbe P erfor mance mcrease more than offsets the 
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connectiorJess P (°r d no "o^en^ requted beforeTtard^r ^ btCrface to this servi « is 
certain local registration as a datagram user is reaped nT* P roceMC ° mm ^cations) however 
Datagrams may be used to either transmit data or si^aTbformation^ SSeS 8 t0 *“* Servke ' 


1.3 Major Elements of a DNET Network 


DNET consists of the following major elements: 

1. A collection of two or more existing, specific networks 

DNET Hosts - machines which are able to communicate using DNET services 

3 . ^rU G g a «Z rks SPeda ' DNET H0StS «“* P-vide protocol convert, between the 
functions. Each of these dSSb' ^ore'd^I “ S ‘ alled WhiCh eslablish ' s ,heir 


1.3.1 Network Arrangement 


DNET is a "meta-network" 
elements of a DNET network 


or a network of networks. The general 
is shown in the following diagram. 


arrangement of these 


major 
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1.3.2 Existing Networks 

The underlying networks associated with DNET are ones which have existing reliable, data streaming 
capabilities. The networks in which DNET may currently operate are TCP/IP and DECnet. 


1.3.3 DNET Hosts 


DNET Hosts are computers at which local processes may use the facilities of DNET to interact with 
remote processes in the heterogeneous network. Any computer connected to one of the networks 

served by DNET may become a node on DNET provided the following conditions apply. The machine 
must: 

1. be resident on a specific existing network (e.g. TCP/IP Net X, SPANET, etc.) which is known to 
DNET 

2. have DNET Host Software Installed & Operational 
Each DNET Host contains the following elements: 
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Software Components 

capability to generate, rowe, read, and vrtelyN^dam” 81138 ' f T C1 ' 0ns whicl1 pro " dc the 
permanent virtual circuit. The major SS/Xt" ^ ““ ^ DNET 

- Establishment of DNET Private Virtual Circuits 
Send/Receive Connectionless Datagrams & DNET Signals 

- Routing for PVCs and Datagrams 

- Interface to underlying communications network(s) 

These are discussed below. 

1. Private Virtual Circuit Service 

vhmud Suit“(PVC) S '™Ta°°PVC ' s ! ablishm ' nt ol » DNET private 

DNET function, d „„*„0 sp^T^ , ‘ prOCe “ a '» "» 

When a connection to the latter ht^bfen^Sed d° ' h ° 5t ' and 

cUew whicb - - -'S^r 25TS 

overhead DNET 

processes at each end of the PVC link P D ™ en the communicating 


2 . 


processes at each end of the PVC link. 
Datagram & Signalling Service 


1 wo types of datagrams are supported 

1 - n “ d » — « *«■ «— 

2 f “ 
3. Routing Software 

DNET employs dynamic, hierarchical routing Each DNFT • . • 

hierarchical routing table in sunnnn r,f .i,;. »• <• acn UINET ° ost maintains a 

local network are direct connecEC h paths ‘° b “ K in ><* 

XiMsss&siir cou,d be 

4. Interface to Underlying Networks connected to the local host 

' .«S',»^, t rrL7 s EL:f e ir -- ° f »>«• ***. 

DNET is installed on a particular host system C °" f ' 8 " at,0 » « «* time 

1. TCP/IP 

2. DECnet 

Pr0CCSS reSP ° ndS l ° reqUCStS fr ° m DNET C,ients for 


4 DNET TECHNICAL GUIDE 



3 . 


4. 


6 . 


7. 


T? Ap P* ication Clients - These are specific DNET applications such as File Transfer etc 
which may be invoked by the user at each DNET host. 

DNET Network Command Interpreter - operates as special command line interpreter to parse 
and distribute DNET commands; The latter allow such operations as I/O redirection and 
distributed command chaining across DNET. 

DNET Application Servers - These are specific servers which are required by a wide range of 
Network user applications on a continuing basis. The number and types of such servers available 
at a specific node may vary according to local conditions. Application servers are controlled by 
systems administrators on hosts in the local domain (network). 

DNET Network Command Server - this ’special’ application server interprets DNET Network 
Command Language commands, executing the local portions thereof, and forwarding those 
portions of the command to be executed at other DNET hosts. 

DNET Datagram Master Server (DGMS) - this is an internal server process which provides local 
control for the datagram service and routing for datagrams to remote nodes. All processes 
wmcft wish to use the datagram service must register with the DGMS. 

8. DNET per Protocol Datagram Server (s) - these are well-known DNET servers whose purpose is 
to forward connectionless DNET datagrams to destinations elsewhere in DNET via specific 
datagram protocols. F 

Tables and Variables 

1 DNET'ISworkT* tblS,myname * Variable containing name of local node and its underlying 

2 nMPT Routing Tab,es • tbls - net - A hierachical routing table which lists the next hop (via a 

DNET gateway) to move toward all distant DNET networks. V 

3 ‘ f SerVer r InU Tab l e ' ' bk msinittc P 311(1 tbls.msinitdec. This is a file containing the 

he nS?T n , 5 formatlon fo V he Master Server - I* is loaded into the Master Server Table when 
the DNET software is started on the local node. 

4 ’ f D hfh MaSte ; l erVer Tab,C ', ThiS table contains a list of allocated DNET apphcation servers on 
this host and their status (not-runmng, idle, in-use). It is used by the Master Server in 
respondmg to DNET clients’ requests for service. 

5. DNET Server Instance Table (s) - These tables list detailed instances of Specific DNET servers 
under control of the Master Server at this DNET host. There is a separate SIT for each type of 
server available at this node. 

6. Connection Lock Table - (not implemented at this time) Used by the DNET Datagram Service- 

lists process/channel/streams currently connected to this host which may be used for the 
forwarding of connectionless datagrams ’ 


1.3.4 Gateways 


n EE Ga ^ ay ^ are nodes “ DN ET which are connected to one or more networks in which DNET is 

network - e i Ct, ° n gatCWay “ t0 bridge the . P rotoco1 “ d differences between these 
r i m 3 ra ^ parent manner - The gateway functions are implemented in special DNET PVC 
Relay servers and Datagram Servers which provide protocol conversion for Permanent Virtual Circuits 
and connectionless datagrams respectively. 

additionsf atCWay ElemCntS indude a11 e,ements of other DN ET hosts with the following variations and 
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Software Components - All of DNET hosts plus 


l. 


0°P‘ *» PVC client/server 

^Tri --pvo^re” ^^^ T aU r a r“ 0 ' n d! : f 

pr'o"ess« bliShed ’ re ' ay Perf ° r ” S emCien '’ ful ' d ”'°” 1 diem a^“ 


Tables - Same as (non-gateway) DNET hosts 


1.4 Layered Model for DNET 
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Application 


DNET 
Applications 
Sc Network Utilities 


Application 
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1.5 Layered Model for Communication Services 


So fa^asTeme/pTaScarthe model attrante^o 3tthe Var - OUS IayerS wkhin DNET Softw are. 
Model. No claim is made that this consistent? is S *™; es defLned b y the KO-OSI 
concepts, and naming conventions from the- nc t a . owever * ^ at her, the use of terminology, 
migration that model® en^olen, mM *" ‘" ,end ' d ,0 *>” * bailed 

1.5.1 Application 

IKSS2 <0r °' her aPpUCa,i °" S > -» “ — .o converse 

Application Services Supported: 

1. File Transfer 

— ASCII and Binary 

- End to End Acknowledgement 

- Data Structures mapped eud to end if context registered with Presentation layer Service 

2. Remote Login 

3. Remote Execution 

4. Mail 

5. General Utilities 

- Status of all network nodes (up/down) 

— Load on remote node 

- Hostid, hostname, alias resolution 

1.5.2 Presentation 

' * — - — — 


1.5.3 Session 


- This layer is null at 


present; All connections are assumed to 


support only one simultaneous session 


1.5.4 Transport 

- DNET Basic I/O Function Library 

- Reliable Task-to-Task Communications 

- End-to-End Acknowledgement of Files, etc. 

- User Authorization, Access Privileges 
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1.5.5 Network 


Defines routing strategies on the Heterogeneous Net 
- Provides Relay function at intermediate Nodes 


-Self Contained within DNET I/O Library, PVC Relays, and Datagram Servers 


1.5.6 Link - Interface 


A Pseudo-Link facility which provides consistent interface 
protocols 


to a variety of underlying network 


Generally, the calls from the network layer 
the underlying, well known protocol. 


to this interface map on a one-to-one basis to calls in 


1.5.7 Link 

— These layers provided by underlying protocols 

1.5.8 Physical 

- Data is assumed to move in a reliable, streaming fashion on any of these links 
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2. Relationships between DNET Components 


2.1 Basic I/O Function Library 

The function calls provided in the DNET basic I/O library are summarized in the following table: 


Generic Operation 

VIRTUAL CKT Client 

VIRTUAL CKT Server 

Datagram 

SIGNAL 

Estab. Connect. 

dn_open 

dngetclient 



Write 

dn_ write 


dn_cwrite 

dn signal 

Synch Read 

dn_read 


dn_cread 

Dest Oper Sys 

A Synch Read 



dncdghandler 

Dest Oper Sys 

End Connect. 

dn_close 

d n_do ne t d n_c lo se 

dncdone 



These functions are described in the following sections 
Connectionless Datagram, or Signal) which they support. 


according to the type of service (PVC, 
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2.2 DNET Objects 

The following table shows the relationships between the various DNET components 
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3. DNET Permanent Virtual Circuit (PVC) Internals 


The fTT desCnbes the , several function calls associated with DNET Permanent Virtual Circuits 
e functions are arranged to indicate those used by DNET client and server processes. 


3.1 Connection Establishment 





1. The client calls dn_open() with parameters including: 

• Network Name 

• Host Name 


2 . 


3 . 


4 . 


• Name of Server 

mmT nirfS* 5 “T 1 “ i<l ' eSS 1“ f '°” ,he l0Cal “ftware. This address is 

sent as part of the connection request datagram to the Master Server. 

If relays are used (required), the relay processes recognize the connection request datagram and 
do not close the connections following transmission of the datagram. q & 

The last relay (or the Basic I/O package on the client if there are no relays) connects to the 
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5 . 

6 . 

7 . 


The Connection request datagram is delivered to the Master Server. 

Using the Master Server Table and a Specific Server Instance Table, the Master Server 
allocates/spawns (VMS/UNIX respectively) a particular instance of the requested server type. 

If service cannot be provided by the Master Server, a service denied or "NAK" response is 
returned to the client. * ^ 


8 . 


If a specific server can be provided, the Master Server 
to this server, sends an "ACK" to the client, then closes 
the connection chain. 


passes the Connection Request Datagram 
its connection to the preceding process in 


9 ' T* ° f the server calls dn getcllentO. Depending on the state of the 

callback_flag in the Connection Request Datagram, dn_getdient() performs either a 
ca h_l°rward or call-back procedure to complete the connection. 


NOTE: If the user wishes to use a specific user-defined process (not a known DNET service) that 
process name should be specified in the initial call to dn_open(). dn_open(), using the networking 
software of the local system, spawns a copy of the named process if that process does not exist already. 


3. 1. 1 Summary of Connection Establishment Sequence 

The several operations described above are shown schematically in the following series of diagrams: 


CVmi 






d*_o 



N«0 



DNET 
Buie I/O 








Gutli 

Kof 



Client Calls dn openQ 


CttMt 



Connection Request Datagram Issued 
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Client 



Connection Request "pulls" Permanent Virtual Circuit Open 


Client 



Last Relay Sends Final Connection Information to Master Server 


Client 



14 DNET TECHNICAL GUIDE 














Clleni 


dn_o xn() 
Pen ling 


DNET 
Bask I/O 



VlatUr 

Server 


Master Server Closes Connection to Last Relay 


Spcdflc 

Server 


DNET Permanent Virtual Circuit (PVC) Internals 15 









S*mer 


Server Calls dn_getclient() to complete connection to Client 


Client 



Server Sends Connection ACK to Client 


CU«m 



Client & Server Interact via dn_write() & dn_read() 
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3. 1. 1. 1 Client S erver Conversation 

Once the PVC is ’open’ data is streamed between client and server processes: 



3. 1.1.2 Closing a Client Server Conversation 

At the conclusion of a session, the DNET permanent virtual circuit may be closed by calling 
dn close(). 



3.2 PVC Client Details 

A DNET Client Process employs the following calls for Virtual Circuit Service: 
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3.2.1 Connection Establishment 

dnopen 

chan = dn_open(net, host, service) 

/* A channel number; 
used in subsequent read and write calls */ 
/* A DNET network name */ 

/* A DNET host name */ 

/* A DNET service */ 

char *userid; 
char *passwd; 


int chan; 

char *net; 
char *host; 
char *service; 


dn_open() is used by client processes 
service a given network and host. The 
opened or an error conditions occurs. 


to request a Private Virtual Circuit connection to the 
function does not return until a path to the destination 


specified 
has been 


3.2.2 Close Connection 

dn close 


status = dn close (stream) 

int status; /* An indication of success or failure 
int chan; /* A channel structure that was 

previously opened using dn_open() */ 


V 


dn_close() closes a communications channel: it 
clients and servers. * 


can be used In 


3.3 PVC - Server 

3.3.1 Receive a Connection 

dngetclient 

chan = dn_getclient (service, usrbuf, pusrbuflen) 

char* service; 
char* usrbuf; 
char* pusrbuflen; 


valid ’channel’ onstream des«^ request C«n the form of a 

Internally, dn_getclient() is slightly more complex: 
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1. A DNET IPC is created for ’receipt’ of future service requests. 

2. dn_done() is called to ’register’ this instance of the server as available in the appropriate Server 
Instance Table. 

3. The program then ’blocks’ on Ipcrcv; it is waiting for an actual service request to arrive from the 
Master Server 

4. when ipcrcv returns, its contents are inspected and disassembled using the function disassemble. 

5. If the Datagram type is callback, dn_open() is used to call back. When dn open() returns a 
channel, this descriptor is passed on to the waiting application server. 

6. If the CR Datagram type is ’stream’, the channel descriptor for this call is passed as part of the 
datagram, dn getclient transparently passes this channel descriptor to the server. 

NOTE: the califorward mode is not currently activated at any server The call forward mode is 
intended for use in Master Server/Application Server relationships where an ’open channel 
descriptor* may be passed from a parent to a child process. UNIX/TCP/IP supports such 
channel passing with ease, DECnet does not. 


7. 


Master 

Server 

Process 


Connect 

Data 


on REQ 
gram 


JL 

IPC 



DNET 
application 
Server 


3.3.2 Notify Master Server of Session Completion 
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dndone 

dn_done is called by each DNET Application Server before exit 
to indicate to the local Master Server that it has 
completed its task and is available for use 

dn done is also called (the first time thru) within dngetclient 
to register the server as available with the Master Server 

dn done() uses a common IPC (DMSTCP or DMSDEC depending 
on the environment) 


3.4 Data Streaming During Session - Clients and Servers 

The functions dn_write() and dn_read() are used by both clients and servers to ’talk’ on an open 
DNET PVC Stream. These functions are equivalent to the UNIX system calls write() and read(); the 
chan on which the operations occurs is an open DNET channel. 

dn_write 

nbytes = dnwrite (chan, buf, nbytes) 

int nbytes; /* The number of bytes, including DNET headers, 
that was written on the given stream. */ 
int chan; /* I/O channel returned from dn_open */ 

char *buf; /* The data that is to be sent. This function 
prepends the data with a DNET header. */ 

dn_write() takes data and packages it in a datagram 

for transmission over the appropriate communications channel. 


dn_read 

Synchronous (Blocking) read 

nbytes = dn_read(chan, buf, count) 

int nbytes; /* The number of bytes, including DNET headers, 
that was read from the given stream. */ 
int chan; /* A pointer to an I/O structure that was 

previously opened by dn open() */ 
char *buf; /♦ A result parameter where the datagram, in 

string format, is placed; this buffer 
contains the DNET headers. */ 

int count; /* The maximum number of bytes to receive. */ 

dn_read() reads a datagram from the communications channel and 
unpackages it based on its type. 


3.5 Master Server 

This section describes the operation of DNET Master Servers. Master Servers are used to control the 
DNET application processes within a single domain (underlying network) on the heterogeneous 
network. The Master Servers are located at any computer attached to the local network which is to be 
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considered a DNET Host. 


Master Servers are also used at DNET gateways to allocate Permanent Virtual Circuit Relay processes. 
Since Master Servers ’listen’ on only one specific underlying network, DNET Gateways must have a 
separate Master Server for each network to which it can provide relay services. (See the Chapter on 
Gateways for additional information). 

5 . 5.2 Master Server Schematic 


Master 

Server 

Process 



i Server i 

i Server i 

1 SIT 

' (DNET ' 

Instance , 

, Instance , 

1 Table 1 

i i 

1 Table 1 

i i 

Server N) 1 

i i 

i (FXFR) i 

i (RLogin) i 


The Master Server Process has several separate functional elements as indicated in the above figure: 

- Server Control Function 

— Server Assignment Function 

The Master Server utilizes the Master Server Table and Server Instance Tables in providing application 
services. 
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3.5.2 Master Server Control Function 


This function has responsibility for the allocation 
local domain. 


and spawning of DNET application 


servers within the 


aysl.LsuchMWX^'i^ ,he °< certain 


3.5.2.1 Application Server Spawning Algorithm 


1. 


S: k ™“.h u e class’ 8 , ,heir pr r ess ; d ' s ror laKr 

another to replace it. a server to a client, spawn 

"1““ » «rv tr . This is .he 

the server up to the tors^ffiSlth^MMl'e! 1 t“r ta7T^We"fe'Lep“thS e th” h 1°“““ ° f 

.h^&r^ ,hc Mastcr w ^ 

4 ' the' ZZ iT^X'^ietT^e^Tr T b " d T ed “ d b ”' ■“» toe. for 

Master Server that they are ready for assignment. " * ' " Mif y the 

3.5.3 Initialization of the Master Server 
3.5.3. 1 Master Server Init Table 

The Master Serve, Ini, Table is read when the Master Server is started at the loeal DNET host. 


DNET Master Server Init Table 1 

Server Type 

Image Name 

# Prespawned 

Mm# 

Init# 

dec hod 

dec hod 

1 

8 

I 

dtftpd 

dtftpd 

1 

9 

4 

drexec 

drexec 

1 

1 

t 

dnstatd 

dnstatd 

1 

1 

i 

dncld 

dncldl 

1 

10 

5 

dlogind 

dlogind 

1 

10 

5 

dmalid 

dmaild 

1 

10 

1 


This is a Ha. ASCII file which may be edited by the local system admimstrator. 

35.3.2 DNET Master Server Table 


^ locTD S h^ er ho a s“ e ,he a nSi C ItT * T * DNET *"*»*» -unable a. 

prespawned, the maximum number available and the" 6 ” 1 K aVa,labIe> whether tfa ese processed are 
to a Serve, Instance table (brSS^S^^ nUn,ber ^ 


An example of the Master Server Table is shot™ in the following diagram: 
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DNET Master Server Table 

ServeiType 

PreSpawned 

Max # 

# Avail# 

In-Use 

Ptr to SIT 

dr exec d 

Y 

10 

5 

2 

78555 

dtftpd 

Y 

10 

5 

2 

79747 

dnmail 

Y 

1 

1 

1 

83297 

dncl 

Y 

10 

5 

2 

99541 

drelavdt 

Y 

10 

5 

2 

81423 


This table is maintained dynamically by the Master Server internal to itself. It may be read using 

dnetstat 

Use of this function is described in the USER’S and ADMINISTRATOR’S guides. 

3.5.4 Example of Application Server Spawning 

The server spawning procedure is shown in the following diagram: 



Master Server Process 


3.6 Details of Specific Application Server Assignment 

3.6.1 S ervice Assignment Function 

The Service Assignment function of the Master Server Process has the task of responding to requests 
for service from application Client Processes at DNET hosts. 

1. Accept Application Server Requests as they arrive at Master Server 
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2. Find available Application Server (or spawn one) by examining Master Server Table and Specific 
Server Instance Table. 

3. Send Connection Information to the Specific DNET Server assigned to this request via DNET 
IPC Mechanism. 

4. Flag server as In-use in Master Server Table 

3.6.2 Specific Server Instance Table 


DNET Server Instance Table 



Server Type = 

File Transfer 

PID 

In-Use 

Time Started 

Time End 

Ptr to MST Entry 

1322 

Y 

10:11 

- 

45779 

1377 

Y 

10:15 

• 

45888 

1422 

N 

10:15 

10:20 

45995 

1428 

r N 

10:16 

10:21 

46100 

- 

- 

■ 

- 

- 

• 

* 

- 

- 

- 


3.7 DNET Gateways 


DNET Gateways are nodes in DNET which are connected to one or more networks in which DNET is 
operating. The function of the gateway is to perform protocol conversion between these networks in a 
transparent manner. Following terminology used by Space Telescope Institute and others, the protocol 
f rf0rmed via DNET servers. The relay functions are implemented in special 
DNET PVC Relay servers and Datagram Servers. The PVC (Permanent Virtual Circuit) servers 

f SUp P°:l P " Vate CUXUItS between communicating tasks while the Datagram Servers perform relay tasks 
lor DNET connectionless datagrams. 
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3.7.1 Permanent Virtual Circuit Relays 

The PVC Relay Servers provide a means of moving DNET stream data between two different network 
protocols. Each relay process is tailored for a specific protocol conversion task. The relays server 
accepts calls from one protocol/network and then establish a full duplex channel. 

PVC Relays are allocated by DNET Master Server Processes in the gateway machine and may thus be 
considered as special purpose DNET Application Servers whose primary function is protocol 
conversion on a data stream. Since Master Servers can only listen on a single network, a gateway has a 
Master Server (and a corresponding ’pool’ of relay processes) for each protocol boundry it supports. 
Each Master Server accepts connection requests from a particular side of a protocol boundary and 
allocates relays from this pool to service the request. 

Relays can be used in routing and communications load balancing. Adding additional relay processes to 
a gateway reduces the delay in accepting data from the network. 

3. 7.2 Master Server Control of PVC Relays 

PVC Relays are controlled by the DNET Master Server in the Gateway machine. The interactions 
between the Relays and the Master Server are very similar to those of any DNET application server. 
Startup and connection passing are identical to other servers. Thus, the relay ralk dn getclfent() to 
complete the connection to the preceding element in the connection rhain 

The ’application’ element of the relay requires establishment of a forward connection on the next hop 
required as part of the connection establishment. This is accomplished by having the each relay call 
dn_open() on its ’server’ side. 

The detailed steps in starting up the PVC relay are as follows: 

1 . 

2. Master Server spawns/allocates ’next_service’ (the appropriate PVC relay in this case) and hands 
the entire ’CR DG’ to the Relay Server. 

3. The allocated Relay Server is waiting on return from dn_getclient() 

4. Waits for "ACK" to be returned from the ’dest service’ (through its call to dn_getclient). The 
’dest_service’ would make the last ’dn_getclient’ call. 

stream = dngetclient ( ); 

When dn getclient returns, the relay then calls dn_open() passing the CR DG to this function: 


3. 7.3 Detail of PVC Relay Function 


The major elements associated with PVC Relays are shown in the following diagram: 
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4. Connectionless Mode Services 


4.1 Introduction to Connectionless Service 

4.1.1 Schematic of Connectionless Communications Service 
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« 4 via gramS Wh “ " 


Source 

Host 


Destination 

Host 


i 

i 

1 Application 
Client ! 


dn_cwrite() 


DNET 

I/O 

Package 


DNET 

Datagram 

Server 


— x 


Application 

Server 


Datagram 


dn_cdg land ler () 


| Gateway 1 

1 i ! 

♦ ♦, 

i Datagram | 

[ Server 

L I 


Gateway 

N 

Datagram 

Server 


DNET 

I/O 

Package 

— A 


IPC 


DNET 

Datagram 

Server 


1 Connection 1 

1 1 1 

r - ~ 1 - - n 

I 1 , 

i Lock i 

Connection 1 

1 Connection 1 

| Connection 1 

! Table | 

< Lock i 

' Lock i 

i Lock i 

i _ j 

Table J 

; Table ' 

1 Table j 


28 DNET TECHNICAL GUIDE 






Applications using the connectionless mode of this service call only two library functions: dn cwrite() 
& dn_cdg_handler() . The initiating process (process sending the datagram) invokes dnjcwrite(). 
Processes which expect to receive datagrams, (in general, all DNET applications), must r ail 
dn_cdg_handler() at start up to identify an "asynchronous completion routine" to be executed whenever 
a connectionless datagram arrives for this process. More complete details on the datagram service are 
provided in a separate Chapter. 

4.1.2 Connectionless Datagram Formats 

The general format of a DNET datagram is: 


struct ass dg buf 
{ 

char desthost[I MAXHNAME] 

char d«stnet[I MAXNNAME] 

char deslprocflMAXPNAME] 

char srchost[I MAXHNAME] 

char srcnet[l_MAXNNAME] 

char sreproc[I_MAXPNAME] 

int maxhops; 

int bufkn; 

char buf[D MAXDG]; 

1 ; 


The DNET connectionless services provides a standard connectionless interface to a heterogeneous 
pool of underlying protocols. The underlying protocols include: 
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• Operating Systems 

• UNIX System V.2 

• UNIX BSD4.2 

• VMS 

• Networks 

• UDP/IP 

• DECnet 


— »f an y of 


per protocol DataGram Server(DGS) 


J h rM b “ i n u , ° t ese com P° nents is to provide a standard interface to the 
DGMS for all underlying protocols. There will be one dgs module set for every 
underlying network protocol ( UDP/IP, DECnet). The UDP dgs module set 
consists of two modules: one for reading incoming datagrams and one for writing 

° ?° mg atagra ™s- The DECnet dgs module consists of one module which both 
reads incoming while sending outgoing datagrams. 

All dgs modules are written as standard dnet datagram programs. This is to say that 
the dgs modules interact with the dgms using the same library routines as any other 

oe ?o^m m thr ° n ' ThC d f erenCe **“8 that ^ ^ve a specific faction to 

feUv h fi h ,S ‘T e , rat ' Ve t0 thC °P eration of dnet. That function is to act as a dumb 
elay between underlying network provider and the dgms module. 


DataGram Master Server (DGMS) 


conn^rf i ^ ‘ h ' S com P onent coordinates the activities of all DNET 
nnectionless components. The dgms module provides two basic services for the 
dnet datagram service: routing and multiplexing of datagrams. 

The routing procedure is driven by the same routing tables used by the dnet 
nection services. The dgms, though, is the only component of the dnet 
connectionless services that provides routing. All other modules know only how to 
pass a partially qualified datagram off to the dgms. The dgms lot up the 
destination network in the routing table and uses the next ne^ork p/otocol to 
determine which dgs module set to pass the datagram on to (It may also just pass it 
ectly to a server process if the datagram is already on the destination machine). 

I?DrTi iple 7, SerVi n PrOVided by the d « ms 15 off of an internal table 

(ADGUT - Active Datagram User Table) which has a record for eve™ 

communication endpoint provided. Included within these records is a string valJI 

SETW* namC that 1S b ° Und l ° 3 g ‘ Ven end P° int - This name is used to 
naml^i Th 1C t h is ‘° j receive a datagram. All processes must bind to a process 

name the time they call dn_cinit if they expect to receive datagrams. The following 

£ are reSerV the datagram Services “ d shoul d not be used in usef 


• dgsudp 

• dgstcp 

• dgsdec 
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Connectionless Services Library 


The connectionless services library will provide DNET connectionless user 
applications with a variety of standard subroutines to access the connectionless 
services. These subroutines include: 

• dn_cinit() 

• dn_cwrite() 

• dn_chandler() 

• dn_cread() 

• dn_cdone() 

• dn_salloc() 

• dn_cerror() 

4.2 per protocol DataGram Server (DGS) 


The primary purpose of the DGS module set is to provide a simple interface to an underlying 
communication provider independent of the underlying communication provider. This interface is 
actually the set of library routines described below and developed for use by dnet datagram 
applications. 

The first step that the DGS module set must perform is to register with the DGMS module. This is 
facilitated through the dn^cinit and dn_chandler library routines. These are the same library routines 
used by other handlers, although the dgms will check for a process registering with one the dgs module 
set reserved names and will interact differently in some situations. The dn cinit call will register the 
dgs module set under it’s reserved name, and will provide a means for passing datagrams to the dgs 
module set’s representative network(s). The dn_chandler library routine is optionally used (currently 
only on dgsdec) to allow for asynchronous receipt of datagrams from the dgms. 

After being properly registered, then the dgs module set is responsible for establishing a protocol 
dependent endpoint for communication with other dgs module sets of the same type on different 
machines. A name is bound to this endpoint for the peer dgs module sets to send to. At this stage a 
perceived full duplex connection exists through the dgs module set from its underlying network 
endpoint to its dnet endpoint. 

The only responsibility left for the dgs module set is to maintain this full duplex connection, thereby 
providing the dgms access to the underlying protocol. To provide this, the dgs module set must 
respond to events on either side of the full duplex connection. For the UDP/IP and TCP/IP module 
sets there actually exists two modules, one for reading from the underlying protocol and passing 
datagrams on to the dgms, and another for reading datagrams from the dgms and passing them on to 
the underlying protocol. The DECnet module set is implemented with only one module, and uses the 
dn_chandler routine to respond asynchronously to datagrams coming from the dgms, while waiting for 
datagrams from the underlying protocol. The DECnet module was designed in this fashion so as to 
work efficiently on the VMS machine. 

The specific details of implementation are discussed in the appropriate sections that describe every 
possible combination. This section will describe the general requirements that every DGS component 
must meet. 

All dgs modules are invoked independently of the dgms, although they will fail if they are invoked 
before the dgms is running. The shell program: startdgms, and the DCL script: strdgms.com illustrate 
an acceptable method of network initiation. A more detailed discussion of the network initiation 
should be found in the administrator’s guide. 
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4.3 DataGram Master Server (DGMS) 


The dgms module provides two basic functions for 
datagrams. 


the datagram services: routing and multiplexing of 


4.3. 1 The Routing Function 


allhough some fwTL e°Ll 


jestnet nexthost relay nextproto 


-rr fie,d u *• — »' * 

relay field is not used by the datagram service rtf * 8 thC dat ?. gram towards **’* destination. The 

s 

^“ s gTabt record ,o p"" “»> ^ 

struct node 

{ 


char host [ I_MAXHNAME] ; 
char net[I_MAXNNAME]; 
char proc [ I_MAXPNAME] ; 


struct udg /* User Datagram structure */ 

struct node sre; 
struct node next; 
struct node dest; 
long maxhops; 
int type; 
long buflen; 
char buf[l]; 

}; 


1£££2£r .«■ — — P » 

the dn cwrite routine) This information is 1! Jl sets avoid this stamping with a special flag on 
P T , d ; the duel application “ 

only lo in, true, the tame* e dgs Id* set as to wht . Tf"?* ^ Md “ «■< 

Hold is currently never used by t£ Z £ 2 “ “ ““ d * ,a *'*“ *° “«• The next net 

be named uniquely when there is a possibility that the ^ module. This requires that machines 

machine. mere ,s a possibility that they null reside on networks common to any gateway 
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na™ and from 1“^^' di'Xd ' '££* 


hostname | netnamc 


<" ««*■ ^ Is used by ,h. dgms to 
determined by looking in the net table.) The hostname HelT^ ^Ty De P VOrk P rotoco1 type must be 
to ascertain when a datagram has reached X £ 27^nZZT f ° r the d ^ s 

• The datagram is at the destination host and network 

• The datagram is at the destination network but is not yet at the destination host 

• f The da tagram is not yet at the destination network 

the dest.network subfield of the datanram l iV^ re< l uire a network table lookup, using 

performed or. rhe uert.pju I„bMdTf“e“ ^ «orUabft“,f “”*■* * 5 

set process to send the datagram to. In addition if the H,? dcten ”“ e •*“ “““ ° f «“ tigs module 
next. host subfield of the network table is used^o lw datagr f m 15 m the tbkd category, then the 
datagram on to. The the Dame of the 8"""* to send the 

field of the user datagram, which is then passed along totfe ** “ the n ° de 


43.2 The Multiplexor Function 


against th e P Activ e P Da^aSaL'ljse^Table 6 (ADGUT) "o^ta "“‘‘T* SU |f ield of the user datagram 
have the name of the destination process in this subfi^lH J gra “^ from thc first routing category will 
routing category will have the process name of the do ’ 'h datagrams ^ rom the second and third 
its appropriate direction. The ADGUT is describedfebw^ “* neCeSSary t0 send the datagram on in 

ADGUT. ThtoG^S^S thlf^oTocLV^^ ° GMS 1Dd entered 11110 **• 

process name to be bound to the datagram comm.. • .™ ay n0 ! bmd , to th e same process name. The 
The dgms is informed of the process name rnca ions endpoint is specified in the call to dn cinit. 
through its service interface. n o er vital administrative or control information 


m«hST s S'^^d U ‘toSl S ^ Slril^sTu P T? (tPC) 

With one I/O descriptor for reading. This requires o^nJ^ d gms has only to contend 

The umt of this abstraction is referred to as a dgms message The^ 0 abstractlon above the datagram. 
Cbe, a datagram or a service request. The folSug 

struct dgms msg 8 ' 

{ 


int type; 
long buflen; 
char buffi]; 
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The type field identifies the contents of the buf field and may be one of the following values: 


DJASGDG 
D MSGSRQ 
DMSGSRS 
D MSGSHD 


User Datagram 

Service Request 

Service Request Response 

Shutdown Advisory — Not currently implemented 


433 The DGMS Service Routines 


The dgms service routines mentioned above provide a means for dnet datagram applications (including 
the dgs process sets) to interact administratively wit the dgms. The interface to the service routines are 
provided through the dgms_serv library routine. 

The dgmsjserv library routine issues a Service Request message to the dgms and awaits a Service 
Request Response message. The service request and service request response are both data structures. 
Your program is required to fill out the service request structure before calling dgms_serv. After 
returning from dgms_serv, the calling program interprets the results left in the service request response 
structure. The following describes these two structures: 

struct srvreq 

{ 

int service; /* service token */ 

int pid; /* process id of requesting process */ 

char pname[D_MAXPNAME];/* requested process name to be bound */ 
char rspipcname [ DMAXPATHNAME] ;/* set only by dgms_serv */ 
char ipcname[D_MAXPATHNAME];/* where to send datagrams */ 
int value; /* service dependent field */ 

}; 


struct srvrsp 

{ 

int service; 
int pid; 

char ipcname[D_MAXFNAME];/* no longer used */ 
char pname[D_MAXPNAME];/* not used */ 
int retval; /* return value */ 

}; 


The following is a list of available services. These services are described in detail later in this 
document. 


DNREQBAS 

DNREQLIS 

DNREQCLN 

DNREQAGS 


Request Basic DGMS Service. Register a process name, send datagrams, and 
receive datagrams synchronously. 

Request Listen DGMS Service. Receive datagrams asynchronously. 

Request DGMS Cleanup Service. Free up any resources tied up by the 
identified communications endpoint. 

Request ADGUT Status Service. Receive a copy of the ADGUT table in its 
entirety. 
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Although the service request message is sent through the same IPC mechanism used for sending 
atap-am messages, the sendee request response messages are sent through a separate, transient IPC 
mechanism. This is due in part to the service routines being used to actually establish the IPC 
mechanism used for receipt of datagrams. 

The dgms serv routine attempts first to establish an IPC endpoint for receiving the service request 
response. The service request always uses the same ipename (dgmsrs) and will make multiple attempts 
to gam access to this ipename in the UNIX environments. In a VMS environment, this will only happen 
to processes under the same login session, because normal user processes do not advertise their logical 
mailbox name, but rather their actual mailbox name through the service request (the vms version of 
ipeget changes the logical name passed to the actual mailbox name) to this rule is the dgms, who uses a 

special flag (and must have SYSNAM privilege) on the ipeget routine to advertise the logical name in 
the system table. 

After an appropriate IPC endpoint has been established, the dgms_serv routine assigns the ipename 
bound to the endpoint (mailbox device name in VMS) to the rspipename field of the srvreq structure. 
The service request is packaged in a message and sent out the standard IPC mechanism used for 
sending to the dgms. A blocking read is then performed on the newly created IPC endpoint waiting for 
the service response. After a service response is received, the endpoint is freed (possibly making it 
available to other processes) and the service response is returned to the function railing dgms serv. 

The following describes in detail each of the service routines supported by the dgms: 

Request Basic DGMS Service 

This request is made by the dn_cinit(3U) user library routine and performs three 
basic functions: 

1. Establish an entry in the ADGUT table to describe the datagram 
communications endpoint. 

2. Establish a means of sending datagrams to the user program by connecting to 
the IPC endpoint specified in the service request structure for receipt of 
datagrams. The user program must have already created this IPC endpoint 
before issuing this request. 

3. Bind the process name specified in the service request to the newly created 
datagram communications endpoint. 

The following fields of the srvreq structure are significant in the DN REQBAS 
service request: 

service = DN REQBAS 

pid This is the unique process identifier to be used when communicating back 
to this process information on the requested service (see below). 

pname This represents an optional process name that the process wishes to be 
bound to so that datagrams sent will have a known process name. If no 
name is given, then the system will not send datagrams to this process. 

value This represents the maximum number of bytes that this process is capable 
of receiving. If a message for this process is larger, it will be truncated, but 
the size field will not be altered so that the receiving process will know that 
there was information lost. THIS IS NOT CURRENTLY SUPPORTED. 

ipename This character string represents the name that may be used by the dgms 
to access the IPC endpoint so that datagrams may be sent to the user 
process. In UNIX environments this is a file name stored in a standard 
directory location. In VMS, this is the fully qualified pathname of the 
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mmlbox being used for IPC. The requesting process should already have 
this IPC endpoint established. 

rspipcname This is an ipename in the same form as ipcname which is used to send 
the service response back to the requesting process. The requesting 
process should already have this IPC endpoint established. 

Response Basic DGMS Service 


The following fields from the srvresp structure are used: 
service = DNREQBAS 
retval 


The retval field may contain the following values: 

0 Successful. The Request Basic DGMS Service control statement 
has completed succesfuUy and the DNET datagram user is now in 
a state where datagrams may be sent and received synchronously. 
The DGMS listen service may also be requested now. 

-1 Internal DNET error. An internal error has occurred. 

-2 No DGMS resources. There are currently no available entries in 
the ADGUT. 

-3 ADGUT quota exceeded. You have exceeded the maximum 
number of entries you may use from the ADGUT table. This is 
not implemented yet due to the fact that only one endpoint per 
process may be established. 

“4 No ipcname. The ipcname you specified for receipt of datagrams 
does not exist, or cannot be accessed by the dgms. 

-5 Name in use. The process name that you requested to be bound 
to your endpoint is already in use by another process. 

Request Listen DGMS Service 


his control routine allows a signal number to be defined (in UNIX environments) 
JPf 0 ,™ 1 “ e r a PP lica tion of a pending datagram. This routine has no 

procMs in theADGUT 6 «“■* '» for this 


service = DNREQLIS 

^ ^rn ary USC °f , thC Pid is . l ° aBow the DGMS signal or interrupt the 
Datagram User to mdicate that a datagram has been received. This 
held should be the same as was specified in the DN REQBAS request as 
it will be used to query the ADGUT. ~ ’ 

pname This field should be the same as was specified in the DN REQBAS 
request, as it will be used to query the ADGUT. 

ipcname This field should be the same as was specified in the DN REQBAS 
request, as it will be used to query the ADGUT. 

value 


This is the "signal" (in UNIX terminology) that will be used to wake up the 
dn_handler routine. This field is required, but is not meaningful in s VMS 
environment. 
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Response Listen DGMS Service 


This control statement will be initiated bv the nrM« ,ft . . _ 

DGMS Service comroi statement. The DGMS™ 8 * “V B “ C 

following fields of the stvresp structure: messag ' "" “ se the 


service = DN_REQLIS 
retval 


m . liw i civ <u ncia 


'-uiiLcun one oi me 


tuuuwmg values: 


-2 


o Successful The Request Listen DGMS message was serviced 

is now a staK “ 

*1 Internal DNET error. 

Bad ar gumenlfs). The specified pid field was less than zero the 

LcTf ed ThcT °°* spcdned -, " “» ipcname field was not 
these folds S ” S “”” 0 ' P"' 0 ™ > k ' ADGUT query without 

3 e ° lry w ““ fo"™ 1 witl1 lhe va lnes supplied for pid 

pname, and ipcname. p ’ 

Request DGMS Cleanup The Request DGMS Cleanup message instructs the DCMS t ft 
IPC meChanism is not -ed for another p 

2SJ2T“ DGMS CICa ” UP ““ *• **>*. from the srvreq 

service = DNREQCLN 

p,d This is the actual process identifier It will be ..«eH to a , 

entries to retnove fron, the DGMS Ust T^wfont 

process name is being shared by more than one 

ipcname » the DN.REQBAS request, as i, will 

Response DGMS Ommr, p The Response DGMS Cleanup uses the following fieids of the srvresp 
service = DNREQCLN 

"■ 32£.t zrjstsss ” *■* 


-1 

-2 


-3 


Internal dnet error. 

Bad argument. The pid field or the ipcname field were not 
specified or were invalid. 

andipc'narne e " ,ry C °“ ld “ f °'“ d «“> *“*ed * 

Request piae. . copy of the enfoe ADGUT into 

*• — -*■ ra ‘ * 
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srvreq structure are significant: 
service = DNREQAGS 
pid Process identifier. 
rspipcname For sending service response. 

Response ADGUT Status The response to DN_REQAGS includes the following fields of 
significance: 

service = DNREQAGS 

ipcname The name of the datafile in the dnet_home directory which contains the 
ADGUT copy. The table is in its binary form and can be accessed using 
the dgms_adut structure defined in dgms.h and described below. 


4.3.4 The ADGUT 


The DGMS Active Datagram User Table is created and maintained internally by the DGMS so as to 
keep track of all processes that interact with it (including all DGS components). 


struct dgms_adut 

{ 

int pid; /* Process Identifier */ 
char pnamefMAXPNAME];/* process name bound to */ 
char ipcname [MAXFNAME];/* IPC name to use to send */ 
int ipcid; /• IPC id used to send messages */ 

int maxmsg; /* maximum size of message this component can receive */ 

int signal; /* Signal number used to inform of pending datagrams */ 

unsigned w timeout;/* timeout period on write */ 

time_t add_time;/* time entry was added */ 

time t last access; 

time_t last_update; 

timet last_send; 

timet lastrecv; 

int state; /* 0 - invalid, 1 - basic, 2 - listen */ 

}; 


Figure L DGMS Active Datagram User Thble 

The pid field is the process id of the process used primarily so that signals or interrupts may be sent to 
the process to inform it of impending datagrams. The pname field is a process name that is bound to 
the process. This allows outgoing datagrams to have a process name, and allows for incoming 
datagrams to be routed to the proper server process. The DGMS will allow only one process to be 
listening on a given process name, although many processes may be sending under a common name. 

The ipcname field is used to keep track of the name of the IPC mechanism used to send messages to 
that particular process. The ipcid is used to hold the id (a file descriptor in the case of named pipes) of 
the IPC mechanism. 

The maxmsg field is not currently supported but is intended to allow a user application to impose limits 
on message sizes that may be passed to them. This is handled now by requiring that all user processes 
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'* “ PabIe °' l '“ d '“ 8 ' hc m ™ m ™ *“ “■'“age, or the biggest message they expect to receive 

— ■*- - h ' ,h * * » - - - ^ - 

the normal amount of time required to relieve itself of a datagram S ’r>n allTrh * “ tendcd *° re P resent 
datagram will be discarded if the message cannnr ^ -On all ot ^ er users applications, the 

appear in the dgms log file to^ndica^thauhis occurred^ 111 * “* "» — » - 

2^sss^tissts2ar“ s,atc ,ha ' an endpoiM is “■ ™- ,ieu » — ^ » 


The time fields are all used to monitor activity of the user applications. 
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4.4 The Connectionless Services Library 


The connectionless services library consists of seven user function calls: 
dn clnit Establish endpoint and basic service state 

Send a datagram towards a destination node 
Declare an exception handler for asynchronous receipt of datagrams 
Read a datagram synchronously 
Free up datagram communications endpoint resources 
Dynamically allocate dnet data structures 
Send a dnet error message (including stack trace) to stderr 


dn_cwrite 

dn_chandler 

dn_cread 

dn^cdone 

dn_salloc 

dn cerror 


4.4.1 The Function Of dn_cinit 


DGMS-S^T-'^ Pla “ S DNET Datagram User a state associated with the Basic 

SB 


4.4.2 The Function of dn_cwrite 




4.4.3 The Function of dn_chandler 


1 SSSSHiSSSSSS 
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1 ** “ * 

Su'Sg sent ‘l re f P ' ° f ,bC *!»“ f “ 1 «* process will restd, 

uid of t„oo, «L win SL’ZS‘2 ZESESZZSSZ? ? DGMS have “ •*<*• 

original call. The exception routine will be^Lssed the addr ^ T r ° Utme specif,ed in the 
datagram just read. P d “ address of the ud 8 structure containing the 

the udg struc^™^s l pa«ed^s ^ S a^ment 'toth* eXcep ! ,on routine is specified, and the address of 
VMS dopientcnta, JU„, Z 


4.4.4 The Function of dn_cread 


receipt of dn,^, ^ 

535 ^ - i - — “ 
- K 35S5 — - - a 

,* h Jtf- ^ -* - velue is se, to 


4.4.5 The Function ofdn_cdone 


Z £ created “* “«‘—™ 

activated by a call to dn_chandler } ‘ * " dn - Cd ° De rout “ e resets any signal handlers 


4.4.6 The Function of dn salloc 


dnbedde^buffeM^be tued^Mh^I^e'ring^of^b^^^l^pt^ 1 ^^ 13 ~ — ■ “ 

may choose the size of the buffer rather than always creating a htff^f ° n “ USCfU ? S ° that a P ro S ram 

used to create reentrant/recursive code sertionc ( ki of maximum size, and can also be 

routine). ‘/recursive code sections (possibly m combination with the dn_chandler 

r T 0ry - The dn - SaJIOC * - d - -any places 
to create a standard -chanism^ b “ «— 
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4.4 . 7 The Function of dn_cerror 


The dn_cerror function is used merely as a last resort to try to display diagnostic information as to why 
something failed. A stack trace of dnet calls is displayed to try to provide insight as to where in the 
user code the failure occurred. 

The stack trace is facilitated within the datagram service code through an array of character arrays that 
hold the name of the library routine called. This array is updated by calling macros defined in the 
dnet_errno.h file. These macros are: 

• DE_push() 

• DE_pop() 

• DE_print() 
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4.5 Component Interaction Diagrams 


t r Ms t ,he «*• ■»« — 

are taken in bringing the network up and in sending a' ^ ° f SteP$ that 
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Figure 2. Schematic Overview of Connectionless Service 


44 DNET TECHNICAL GUIDE 









This represents an empty machine, 
underlying protocol providers. 


The only components of interest existing on the machine are any 
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Here, the DataGram Master Server is started either manually by 
regular boot up procedure in the machine. The DGMS will 
activity and so will be the first component started. 


a systems administrator, or through a 
coordinate all connectionless service 
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e GMS will first create the process communication medium. This will be one form of 

r“f‘° n that Wl11 be used b y 311 components when interacting with the DGMS. This will allow 
d^e DGMS to concentrate on reading from only one entity. The communication medium must support 
message oriented service. The message oriented service will provide for the synchronization of 
otherwise potentially non-atomic writes over a single IPC mechanism potentially shared by many 
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Figure 6. Invocation of DGS Components 
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2 . 


3. 


4. 


Tl !f °GS P rog ram selsarc started independently of the dgms program. These issue the dn cinit 
cail, which establishes the IPC communication endpoint for receiving datagrams and connects to 
t e standard IPC communication endpoint for sending messages to the dgms. 

d^s sen/) COnneCtl ° n ^ ^ dgmS * SerViCe request ( DN _REQBAS) is made (via 

The dgms responds to the service request by establishing a dnet datagram communications 

" s ,he req " es,ai proc ^ name <d ' !s,c ' , <, * sd “ <■ > 

Finally the dgms connects to the IPC endpoint created by the dn cinit routine in step 1. This 
simp ex connection will be used to send datagrams to the dgs program sets. The service response 
is sent through a transient IPC mechanism created and maintained by the dgms serv routing 


52 DNET TECHNICAL GUIDE 




Figure 7. dn_cinit process 
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The dnet user application uses the 


same procedure as the DGS program sets in accessing the dgms. 
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2 . 


3. 


4. 


6 . 


1. The dn cwrite will send a message containing a datagram with a DGMS Message Header 

^ S Pr0CeSS CO "" , ™ i °» 

The DGMS component consults the routing table to determine the address of the next hon f after 

ssk **■ ,he - 

The DGMS sends a message out to the process communication medium of type datagram and 
the routing tabled ^ ^ ^ Pr ° Per ° GS com P onent ^ read * (this is determined from 

If necessary (in dgsdec only) a signal is sent to inform the module that a datagram is nendino r>h 

- — 

t" n e“r rr^,^ or 

connectionless sendee, then a connection is e’stablished for to bTsenT SUPP<m * 
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1 . 


2 . 


3. 


4. 


5. 


After achieving the state associated with Basic DGMS Service, the DNET User component is 
able to move to the state associated with Listen DGMS Service. The dn chandler sends a 
R equest Listen DGMS Service message to the process communication medium under the hard 
coded key value used to communicate with the DGMS (the same value used when sending the 
Request Basic DGMS Service message). 

The DGMS reads the message sent to it and interprets it as being a Request Listen DGMS 
Service message. 

Assuming the component sending the Request Listen DGMS Service message is in the proper 

T St ha r P revious| y sent a Request Basic DGMS Service message and be listed in the 
-MS-tive Datagram User Table), the DGMS will modify the entry in the Active Datagram 

The DGMS sends a Response Listen DGMS Service message out to the DNET Datagram User 
with the ipename specified in the Active Datagram User Table. Information included in this 

message includes the DNET User Identifier, and key value which may contain a negative number 
indicating an error. 

The dn chandler routine will have been waiting for the Response Listen DGMS Service message 
over the standard response ipename (this all happens in the dgms serv internal library routine) 
After reading a successful response, the DNET Datagram User will now be in a state associated 
with the Listen DGMS Service and is capable of sending datagrams as well as responding to 
datagrams sent to it. F K 
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Figure 10. Receive Datagram at Destination 
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2 . 


4. 


When a datagram arrives from another host, the underlying protocol passes it to the DOS 
component performing the blocking read on that particular protocol. 

^l D ° S rT P ° a T imertS the DGMS Messa S e Header on the datagram to form the datagram 
message (the exact message type that the DNET User component forms when sender a 

- 

rdat“a” S r e Sge he ^ ““ "«dium and taerpreu ,ha, i, is 

rT tha ‘ lhaI datagram is destined to, this host, and so it checks the 

“ datagram The' S “f"'’ ‘ he ^ < if that “ waiting <o “«e « 

l ive S ^aJ usS' 0 " 55 ' D “ nd ‘ to ^ Val “' '° r ' his *“ <* P" from the 


5 . 

6 . 

7 . 


raedi,m ‘ ™ ,h ,he kty ^ 


If the state associated with the intended destination of the 
received datagrams asynchronously, a signal is sent when the 


datagram is 2, indicating that it 
operating system environment is 


The DNET User component will read the message waiting for it 
medium. & 


on the process communication 
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Figure 11. Receive Datagram: at Gateway 
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1. A datagram is received by the underlying protocol and is passed along to the DGS Component 
associated with that underlying protocol. 

2. The DGS component inserts the DGMS Message Header and places the message in the process 
communication medium with a key value such that the DGMS will read it. 

3. The DGMS reads the message and determines that it is a datagram message. 

4. The DGMS determines that it does not represent the destination machine, and so consults the 

Routing Table to determine the next hop. 

5. The DGMS changes the next hop node in the user datagram structure to state the node 

information of the next hop and places the datagram message back into the process 

communication medium with a key value such that it will be read by the proper DGS component. 

6. If necessary, the dgs program (dgsdec only) will be sent a signal if it resides on a UNIX machine. 

7. The DGS component will then read the datagram message and prepare the internal structures in 
preparation for passing it along to the underlying protocol. 

8. The DGS component will then pass the datagram along to the underlying protocol provider. As 
stated previously, any provision for support of connectionless service in an underlying protocol 
which otherwise does not support a connectionless service is the responsibility of that DGS 
component. 
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5. DNET Interprocess Communication (IPC) 


5.1 Introduction 

The standard IPC implementation was created to provide a standard means of communicating between 
processes running in varied environments. These means must be capable of providing services 
necessary and reasonable for both the connectionless and connection services. The following 
summarize the requirements placed upon the IPC services: 

Independence from DNET 

The mechanisms should serve all of the needs of the dnet services but should 
avoid (where possible) imposing dnet constraints. These constraints could be 
usage of global constants defined in the dnet domain, or reliance upon dnet 
locations within a file system, or the usage of functions defined within the dnet 
domain. THIS REQUIREMENT HAS NOT BEEN COMPLETELY MET 
MOST VIOLATIONS OCCUR WITHIN THE VMS ENVIRONMENT. 

Implemented under BSD UNIX, System V UNIX, and VMS 

The standard IPC implementation should be accessed the same regardless of 
the operating environment under which it was created. This was the primary 
reason for creating the standard IPC implementation, so as to provide a 
standard interface for communicating with other processes on the same box. 

Simplex IPC mechanisms 

The IPC mechanisms established need only be simplex. This requirement is 
stated to allow for economizing resources. If a full duplex connection is 
required (the exception rather than the rule in dnet), then two mechanisms 
may be established. In two of the three operating environments, this does not 
require any more resources than an actual full duplex mechanism. 

Message oriented transmission 

The message oriented transmission is required mainly because of the need to 
have a single reader responding to many writers. The IPC mechanisms 
themselves are more capable of managing messages than is the receiver 
capable of making messages from a stream. All operating environments 
provide a direct IPC mechanism for passing messages. 

Oriented towards endpoint establishment 

The endpoint establishment should be contrasted with a "mid point" 
establishment such as the message queues used in System V UNIX. The mid 
point establishment allows a common area to be logically set up where 
messages may be placed (a bulletin board of sorts), all members are then able 
to pick any message sitting in the mid point. The endpoint method allows one 
process to advertise an address which can be globally sent to, but only locally 
read. The BSD socket interface is an example of endpoint establishment. The 
VMS mailbox devices would fall into the category of mid point. The endpoint 
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establishment requirement was set down mostly because it is easier to force a 
midpoint type IPC mechanism to act like an endpoint type IPC mechanism 
than vice-versa. 

Addressing via character strings 


All IPC endpoints should be addressable with character strings. There are 
some limitations to this including length and use of special characters like "/“ in 
UNIX and in VMS. The BSD and VMS provide direct addressing of 
endpoints with character strings. The conversion used for System V message 
queues is discussed in the section on implementation for System V. 

Independence between peers 

All interactions across the IPC mechanisms should be performed 
independently of the action or availability of the peer. If the bufFer between 
the peers is full, then the sender should have the ability to fail the write without 
wasting time blocking. In no case should the success of the write be hinged 
upon the availability of a read. 


5.2 Interface 


T e interface to the IPC mechanisms is intended to be similar to a socket interface, but simpler 
because of less required functionality. In addition, and more important, the interface should be 
independent of the operating system, although there still exist some subtle differences. Finally there is 
a provision for binding and connecting (like the socket interface), but the simplex nature of the 
connections allows this provision to be included in the library routine to establish the endpoint. 

The following, then, are brief descriptions of the library routines making up the general IPC interface. 


5.11 Administration Of IPC Medium 


To provide for full flexibility, it is necessary on some operating systems to create a medium for the IPC 
mechanisms. This medium may include an environment for name translation or location (UNIX) or 
may require that a chunk of the operating systems IPC "medium” be reserved for use by the set of 
T°iDr mg 4 PrOCeSSeS (System V). The VMS operating does not require the administrative creation of 
the IPC medium, and in that environment merely no action is performed on an attempt to create the 
medium. r 




64 DNET TECHNICAL GUIDE 



5.2. 1.1 The jnakeipc function 

J'l e Kr I li akeipC i UnCt ‘° n all ° WS for the administrative creation of an IPC medium necessarv for 
declaratioif of jnakdpc: ' PC m “ h “' SmS for blowing is a listing of the 

int _makeipc(svjnsgjcey, ipcdir, flags) 

int sv msg key; /* System V message key value */ 

char ’ipcdir; /* UNIX directory where addresses will reside */ 

int flags; /* DCREAT, DEXCL •/ 

L h l S ;^ Sg - key argUment is on 'y pertinent in the system V environment (although a value mav be 

gsr your adm “ s,ra,OT « - * *■ - 

S? L^TLd ^ ™» « - absolute pathname for the 

and ,s being used, an examination of this directoty will reveal the active connections “* 

ItoSaSThV D°«^^ f Th‘ h ?d C K a,i °“ ° f ' hC IPC medil,, ”• Wk '“ lbis “ called 

— i « dts D „-o C , R e“, T ui suggested ~ D 'S £ 7 f «“f f 

D.EXCL ,o insure that two administrat “processes L 

medium. 1 ^Is^aC" o™ed rSou^itdtlo* 

arguments with the impu7ecall’ < Eia'de by the Ime'r calk'to°ip^et h ^ Vhe hnTt'Sl “““ d®"' “ 
ipcge. using the maheipc (no preceding u^m, ££ S JZST ZSZiSZ ** 

if(_mak*ipc(DNET IPCKEY, DNET IPCDIR, D CREAT) == -l) 


preprocessor constants as arguments along with the D CREAT°I D^Elff^n* cxpbca ’ cly Usmg tllc 
routine „il, use the same valuTwhen aSX»nd£^ 

IpC medium® “ “ C ° d ' °° admimttrative creation of the 
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# Include "dnet_ipc.h* 

# define DNET IPCKEY 1504 
#define DNET IPCDIR Vtmp/myapp" 


if(_makeipc(DNET_IPCKEY, DNET_IPCDIR, D_CREAT | D EXCL) == -1) 


} 


fprintf(s(derr, ’makeipc failed: dnet errno(%d) ermo(%d).0, dnet errno, ermo): 
retum(-l); 


5.11.2 The jemoveipc function 

The _removeipc routine is provided to clean up the IPC medium created with the makeipc routine 
arguments are passed to the removeipc routine because the IPC module keeps track of the 
arguments used to call _makeipc. The environment will only be removedTo m the S !ltem if £ 
makeipc routine was called by someone with both the D_CREAT and D EXCL flags set Onlv the 
process that actually created the segment will be allowed to remove it. All other processes will return 

SSSSSss— — s&fcsS 


5.2.2 Administration Of Individual IPC Mechanisms 


The individual IPC mechanism is a logical device which provides for simplex transmissions between!™ 

Sstbg lP? medil C0 ' The" maCh ^ Th T mechanisms should assumed to be reliant upon an 
descried -m the section atove ” ^ ** the P re P rocess °r constants 

The responsibilities of the program in administering individual IPC mechanisms is the establishment of 
the endpomt and the cleaning up of the endpoint when the program is through ^ h estabhshment of 

^vo ^routines are provided for these purposes: ipcget and ipcclose. A description of these routines 

5.2.11 The ipcget function 

The ipcget function provides for the establishment of an IPC endpomt and provides for either a 

bS ^ t0 that , e “ dpomt > ° r a connection to be made to another endpoint with an address 
for rith ' Aft successful ipcget, the endpoint is an established IPC mechanism and may be used 
o either receiving datagrams (if bound) or sending datagrams (if connected! No snnnnrt f 
conoeci'onlcss endpoint exisis where «he address is 

md or connect to a different address is the remove the endpoint and reestablish. * * 


The following is the declaration of the ipcget function: 
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int ipcget(name, flags) 
struct dnet_ipcname *name; 
int flags; 

The dnet_ipcname structure consists of the following fields: 

struct dnet_ipcname 
{ 

char name[D MAXPATHNAME]; 
unsigned maxmsg; 
unsigned maxmq; 

}; 


The maxmsg and maxmq fields of the dnet ipcname structure are not currently used. The name field 

T ' he r a f dreSS , (a Sim P ,e character string) that your program wishes to have bound to its 
endpoint, or of the endpoint of another program to which your program wishes to be connected. 

The flags argument must have one and only one of the following flag values set: 

D CONNECT Find the IPC endpoint to which the address in ipcname.name is bound and connect 
to this endpoint. 

D_BIND Bind the address in ipcname.name to this endpoint. 

r n addition, the D GL OBAL flag may be set in combination with the D BIND flag to force the 

er:i° be adV t ertlSed ^° bally u across the current machine. This flag only has significance in the 
VMS ennronment since this is the norm in a UNIX environment. In order to have the address 
globally advertised, the process must have SYSNAM privilege. 

The ipcget function returns an integer ipcid on success. This is similar to a file descriptor but is not 
Instead it is translated to a file descriptor, channel descriptor, or message type when used. This will be 
discussed more in the implementation section. mis win oe 

The following examples demonstrates the suggested usage of the ipcget library routine. The server 
program example is binding the address to its endpoint (thereby advertising the address) while the 
client program is connecting to the advertised address (at a time after the server has bound/ 

Server Program 


#include "dnet ermo.h" 


int ipcid; 

struct dnetipcname i pc name; 


strcpy(dnct_ipcname, "myaddress"); 

if((ipcid = ipcg*(&dnct i pc name, DBIND | D GLOBAL)) = = -1) 

{ 

q>rinlf(s«derr, "ipcg«:dnel ermo(%d) ermo(%d).0, dm* errno, ermo); 
retum(-l); 

> 

Client Program 
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# include "dnet ermo.h" 


ini ipcid; 

struct dnet j pc name i pc name; 


strcpy(dnet_ipcname, "myaddress"); 

if( (ipcid = ipcgetC&dnet ipcname, D BIND | D GLOBAL)) == -1) 

{ 

fprintf(stderr, "ipcgrt:dnet_errno(%d) ermo(%d).0, dnetermo, crmo); 
retum(-l); 

} 

5. 2. 2. 2 The ipc close function 

The ipcclose function frees resources associated with the IPC mechanism identified by the ipcid which 
is passed as an argument. On UNIX systems, this will also unlink the file entry in the DNET IPCDIR. 


5.2.3 Sending And Receiving Messages 


Tworoutmes are provided for sending and receiving messages over an established IPC mechanism 
Validation is performed on each transaction to insure that the mechanism is capable of 
sending/receiving a message. Because the mechanisms are simplex in nature, the routines will not 
allow a message to be sent out an endpoint that has a bound address, and will not allow an attempt to 
read from an endpoint which is connected to a peer endpoint. 

The descriptions of these two functions: ipcsnd and 3ipcrcv follow: 

5.23.1 The ipcsnd function 


The ipcsnd function allows a message to be sent out through and endpoint that has been successfully 
connected. The declaration of the ipcsnd function follows; 


in* ipcsnd (ipcid, umsg, umsglen, fteg) 

ini ipcid; 

char ♦umsg 

ini umsglen; 

ini flag 


The Ipcid argument is the endpoint identifier returned by the ipeget function. The umsg argument 
points to the buffer (binary data is acceptable) containing the data to be sent, while the umsglen 
indicates the number of bytes to be sent. The flag argument may have the D NOWAIT flag set which 
Will force the send to be non-blocking. ~ 


The following is a section of the same client program 
routine. Because of the simplex connections, only 
routine on this IPC mechanism. The client program 
this IPC mechanism. 


above demonstrating the use of the ipcsnd library 
the client program is allowed to use the ipcsnd 
is not allowed to use the iperev library routine on 
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char umsgfDMAXMSG]; 
int u ms glen; 


strcpy(umsg, This does not have to be an ascii string”); 

umsglen = strlen(umsg) + 1; 

if(ipcsnd( ipcid, umsg, umsglen, 0) = = -1) 

{ 

fprinlKstderr, ”ipcsnd:dnei_errno(%d) errno(%d).0, dneterrno, emu); 
retum(-l); 

I 


5.2.3. 2 The ipcrcv function 


The ipcrcv function allows a program to read a message from an endpoint that has an address 
it. A description of the ipcrcv function follows: 


bound 


to 


int ipcrcv(ipcid, umsg, umsglen, flag) 

int ipcid; 

char *umsg; 

int umsglen; 

int flag; 


The ipcid argument again identifies the endpoint over which the program wishes to receive a message 
The umsg argument points to the buffer where the message will be placed, and the umsglen argument 
states how large that buffer is in bytes. The flag argument may have the D NOWAIT flag set which 
will ms ure that the call does not block. ~ 8 

The following is a section of the server program above demonstrating the use of the ipcrcv library 
rou me. ecause of the simplex connections, only the server program is allowed to use the ipcrcv 

on t^IPc' * The SCrVer n0 ‘ 1 " 0WBd l ° ^ the ipCSDd Ubrar y routine 


char umsg[DMAXMSG]; 
int umsglen; 
int readlen; 


umsglen = DMAXMSG; 

if(( readlen =* ipcrcv(lpcid, umsg, umsglen, 0)) = = -1) 

{ 

fyrintf(stdeiT, ’ipcrcvtdn* «mno(%d) ermo(%d).0, dnet errno, ermo); 
retum(-l); 

} 
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53 Implementation 


This section will discuss the unique features of each operating system that were used to implement the 
standard IPC implementation. 


5.3.1 The ipcid Table 


The IPC module maintains a table of all active endpoints for a particular 
similar in function to the file descriptor table in UNIX operating systems, 
table follows: 


process. This table is very 
A short description of this 


static struct 

{ 

char name[D_MAXFNAME]; 
int flag; 
int id; 

}ipctab[D_MAXIPCIDS]; 

The name field contains the address used in this IPC mechanism. The flag contains the flags specified 
on the ipeget, and the id contains a numeric value describing the lower level IPC mechanism. In 
System V environments this si a message type, in BSD environments it is a file descriptor for a socket 
and in VMS environments it is a channel descriptor. 


5.3.2 System V 


The System V message queue facility was used to implement the IPC implementation on System V 

T: at ^ systems - This facUity required work on three areas to bring it in line with the requirements 
or the IPC implementation; 

• Standard interface 

• Endpoint establishment 

• Character string addresses 

A description of the implementation of the standard interface follows; 

jnakelpc The ipc directory is created if requested and necessary. The message key value is 
used in attempt to create a new message queue for use by all processes using the to 
be created IPC medium. If the D_CREAT flag is not set, then an attempt will be 
make to look up an existing message queue with a matching key value, and will fail if 
one does not exist. If the DCREAT flag is set, then the queue will be created if it 
cannot be found. If the D CREAT and DEXCL flags are set, then the call will only 
succeed if a message queue with the requested key value did not previously exist. 
The flag values are used in a similar nature for the creation of the ipc directory. 
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removeipc If it is determined that this program called jnakeipc with both the D CREAT and 
D 7i E i XC f L ^8® set, then the ipc directory will be removed, and the message queue 
will be freed and returned to the system. In all other cases the call always returns 
successfully. 

ipcget The ipcget routine attempts to find a file in the ipc directory with the same name 

specified as the address requested in the ipname structure. If the D CONNECT flag 
is set and the file exists, then a message type value is determined (as described 
below) and is placed in the id field of the appropriate entry in the ipcid table. 

If the D_BIND flag is set, then a file is created in the ipc directory, a message type 
value determined and is placed in the id field of the appropriate entry in the ipcid 


ipcclose 


Ipcsnd 


ipcrcv 


The ipcclose routine will remove the file from the ipc directory as long as the 

D BI NE> flag was used on the ipcget. If the D_CONNECT flag was used, then the 
file will remain. 

The ipcsnd routine packages the message into a System V message queue structure, 
sets the message type field to be that of the id field in the ipcid table and adds the 
message to that queue. 

The ipcrcv routme attempts to read a message from the queue where the message 
type matches the id field in the ipcid table. 


along the midpoint characteristics of the message queues emulate endpoint characteristic was 
accomplished by creating file nodes in the ipc directory for every IPC mechanism (note that this is for 
every mechanism and not for every endpoint). This allows a simple check to be done to insure that 
before an attempt to bmd is made, that there is not another process bound to that address, and that 

receive 311 3ttemPt COtmeCt 1S made ’ that another P rocess has bound to that address and is ready to 

Mapping a character string name to the message type value was performed by merely obtaining the 
inode number of the file node created for the IPC mechanism. Because all file nodes are created on 
the same file system (they are all m the same directory), the inode number is unique. In addition the 
inode number is the same for every process that checks it and so provides a stable conversion 


5.5.5 BSD 


The BSD socket interface was used with the UNIX address family as the underlying mechanism of IPC 
in Berkeley UNIX systems. This facility required work only in the area of interface to bring it in line 
wit the requirements of the IPC implementation. One apparent bug in the operating system makes 

the IPC mechanisms system hogs during excessive use of the IPC mechanisms. This is discussed in the 
description of the ipcsnd interface. 

A description of the implementation of the standard interface follows: 

jnakeipc The makeipc routine creates/references the ipc directory in a fashion identical to 
that of the System V makeipc. 


_removeipc 


ipcget 


The ^removeipc routine acts identical to the _removeipc routine of System V 
excluding the freeing up of the System V message queue. 

The ipcget routine translates almost directly into a socket system call followed by a 
bind system call if the D_BIND flag is set or a connect system call if the 
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ipcclose 


ipcsnd 


iperev 


D CONNECT flag is set. The file descriptor returned by the socket system call is 
placed m the id field of the appropriate record in the ipcid table. 

The ipcclose routines uses the close system call on the file descriptor in the ipcid 
table, and then, if the D_BIND flag was specified on the ipcget, then the file node is 
removed explicate^ from the ipc directory. The BSD system does not yet remove 
the file nodes it creates on the bind system call. 

The ipcsnd maps almost directly to the send system call. There exists a bug, though, 
in the BSD implementation of the IPC on send where, even when blocking mode is 
set (this is by default), the system will return with a E NOBUFS error when there is 
a transient shortage of buffers in the system to place the message. With that attitude 
that this bug will be fixed, the ipcsnd routine loops (eating up valuable CPU 
resources) until the message can be taken or a more definitive error occurs. 

The ipcrcv routine maps directly to the recv system call. 


5.3.4 VMS 


e VMS mailbox interface was used as the underlying mechanism of IPC in VMS systems. This 
ac ty require work in the following areas to bring it in line with the requirements of the IPC 
implementation. The VMS system, in addition actually fails implied requirements of the IPC 
implementation in that SYSNAM privilege is required to advertise globally. To partially overcome this 
die ipcget routine in VMS returns the actual device name of the mailbox accessed by the ipcget call! 

his name may be passed through some means, to the person attempting to connect to your endpoint 
The problem with this is that the fully qualified mailbox name can be very long (especially in cluster 
™ p n “ entS> - Thls re ? ui f u d that IPC implementations increase their overhead^ aaLmodate 
this time*™ SPaCe reqUlfed by VMS- This ^ be overc ome, but lack of time and resources limit us at 


• Standard interface 

• Endpoint establishment 

• Independence between peers 

A description of the implementation of the standard interface follows: 

jnakeipc This is an effective noop function call in VMS. 

removeipc This is an effective noop function call in VMS. 

ipcget This is probably the most complex of all the IPC routines because of all the facilities 

potentially touched. In general, a channel is assigned to the address specified in the 
name field of the ipename structure if the D_CONNECT flag is set. The name field 
is either a logical name which will translate to a mailbox device name, or is the direct 
mailbox device name itself. If the logical name cannot be translated, and error is 
returned indicating that no peer exists. 

If the D BIND flag is set a mailbox is created. A logical name is equated to this 
mailbox, and a channel is assigned to the logical name. This results in the logical 
name being placed in the job table. If the D_GLOBAL flag was set, then an attempt 
is made to assign the same logical name to the system table. In both events for the 
bind, the device name of the mailbox is copied over top of the logical name in the 
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name field of the dnetipcname structure. The channel number is placed in the id 
field of the appropriate ipcid table entry. 

ipcclose If this endpoint had an address bound to it, then the logical name entries are 

removed from all appropriate tables, and the mailbox device is freed for use 
elsewhere. 

ipcsnd The ipcsnd routine is implemented with the standard SYSSQIOW system service. 

The VMS mailbox facility will normally attempt to hold the write outstanding until a 
peer has attempted to read it. The IO$M_NOW flag was set to force the write into 
the mailbox and prevent it from remaining outstanding. 

ipcrcv The ipcrcv routine is also implemented using the standard SYSSQIOW system 

service. 

The requirement of endpoint establishment is not met under VMS. Two sticking points still exist: 1) 
The global advertisement of addresses requires SYSNAM privilege (which is an unfeasible 
expectation) and therefor opens the door to multiple processes binding to the same name. In addition, 
the logical tables are allowed to be overwritten with new values, meaning that no check is performed 
to see if the name has already been bound to. The dnet services currently compensate for this under 
VMS environments. 

The requirement of peer independence was met through a combination of the IO$M_NOW flag and 
the SYSSSETRWM system service. The IO$M_NOW flag was set in the ipcrcv routine to initiate a 
non-blocking read. In the ipcsnd routine, the IO$M_NOW flag must always be set, and the 
SYSSSETRWM system service was used to temporarily set the resource wait mode from its default of 
waiting for the resource to the state in which it will fail if the resource is not available (a full mailbox in 
this case). 
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6. Miscellaneous DNET Internal Utilities 


This section describes miscellaneous utilities which are internal to DNET. 

6.1 General System Utilities 

6.1.1 getppid 

6.1.2 fperror 

6.1.3 iosync 

6.1.4 is_error 

6.1.5 prttime 

6.1.6 stricmp 

6.2 General Network Utilites 

6.2.1 check jny net 

62.2 disassemble 

62.3 dnjnit 

62.4 dnjnakedg 

62.5 dnjnakepvc 

63 Stream to Datagram Conversion Utilities 

63.1 strtodg_dglen 

63.2 strtodgjnsg 

63.3 strtodgjvumhops 

63.4 strtodg_path 

63.5 strtodgjjathlen 

6.3.6 strtodgjtream 
63.7 strtodgjtream _msg 
6.3.8 strtodgjype 

6.4 UNIX Specific Utilities 

6.4.1 build _argarr 
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6.4.2 execs hell 

6.4.3 startserver 

6.5 VMS Specific Utilities 

6.5.1 create jnailbox 

6.5.2 execs hell 

6.5.3 getargs 

6.5.4 gobetween 

6.5.5 setargs 

6.5.6 startserver 

6.5.7 lib _do _command 

6.5.8 lib _spawn 

6.5.9 sys _assign 

6.5.10 sys _cancel 

6.5.11 sys_crelnm 

6.5.12 sys_crelnt 

6.5.13 sys_crembx 

6.5.14 sys_creprc 

6.5.15 sys_dassgn 

6.5.16 sys_dellnm 

6.5.17 sys_delmbx 

6.5.18 sys_getdvi 

6.5.19 sys_getjpi 

6.5.20 sys_getmsg 

6.5.21 sysjtiber 

6.5.22 sys_qio 

6.5.23 sys_qiow 

6.5.24 sysjmlnm 

6.5.25 sys_wake 

6.5.26 vmsjperror 

6.5.27 vms _perror 

6.5.28 vms_read 

6.5.29 vms _write 

6.6 MS DOS Specific Utilites 

To be added 
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7. Interfaces to Underlying Networks 


Both the Datagram Assembler/Disassembler and the Router of the BASIC I/O Package connect to 
underiymg networks via the Network I/O Interface. This interface "maps" generic function calls 
(dn_open, disclose, dn_read, dn_write, etc.) into protocol specific functions for a particular network. 

The files tcp.c and decnet_nt.c in the network specific interfaces for most TCP or DECnet systems 
The files exostcp.c contain 


7.1 Underlying Network Protocols 

Wherever possible, existing, well known network protocols are employed in order to achieve reliable 
communication services between DNET nodes. These protocols are internally sophisticated, typically 
containing their own quemg, buffering, retry and timeout mechanisms as well as their own routing 
“ e ‘ r own network domain. Despite this internal complexity, it is important to note the 

- From the DNET perspective the protocols provide point to point link and physical level services 
between nodes defined in the the DNET network. 

For each protocol the following generic functions are provided: 

- Open 

- Init_Permanent_Server 

- Init_Transient_Server 

- Get_CIient 

- Close 

- Read 

- Write 

- Async_Read 

- Wait 

Two protocols are currently supported within DNET. These are: 

1. TCP/IP 

2. DECnet 


The specific interfaces to these protocols are discussed in the following sections: 

7.2 TCP/IP 


nr' mp eme “ tat r °f T< r P/IP 31-6 m use within DNET - The usage varies with the particular 
DNET node. The three implementations of TCP/IP currently supported together with the relevant 
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host machines are: 

1. Berkeley UNIX - DAC & NASA Sun’s 

2. Wollongong - DAC MicroVAX II and 3B2/600 

3. Excelan - NASA VAX’s 

Common source code is used for all three implementations. This code is located in the file tcp.c. 

73 TCP/IP Specific Utilities 

The following ’tcp/ip’ specific functions are supported by DNET: 

7.3.1 tcp_accept 

7.3.2 tcp_close 

7.3.3 tcp jetclient 

7.3.4 tcpjnitperm 

7.3.5 tcpjnittrans 

7.3.6 tcp_open 

7.3.7 tcp jpvcopen 

7.3.8 tcpjead 

7.3.9 tcp_write 

The reader is referred to the source listings for tcp.c for further details on these functions. 

7.4 DEC net 

Source code for the DNET interface to DECnet is found in the source files decnetx and decnet 
The supported functions include: 

7.4.1 _decnet_read 

7.4.2 decnet _accept 

7.4.3 decnet _close 

7.4.4 decnet _errgeneric 

7.4.5 decnet _errprotocol 

7.4.6 decnet _getclient 

7.4.7 decnet Jnitperm 

7.4.8 decnet Jnittrans 

7.4.9 decnet _open 

7.4.10 decnet jpvcopen 

7.4.11 decnet jead 

7.4.12 decnet select 


nt.c. 
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7.4.13 decnet_write 

7.4.14 vms_aread 

7.4.15 vms_awrite 

7.4.16 vms wait 
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8. User Application Internals 


8.1 File Transfer Protocol 

The DNET File Transfer protocol 


dtftp transfers blocks in fixed size (512 byte) units. Acknowlegements are sent by the receiving host’s 
file transfer server (dtftpd) after each block has been received. Error reporting packets include the 
following: 


8.2 Schematic of File Transfer 


Connect, Get 
Put, etc. 



8.21 General Considerations 

TTie receiving host tests for existance of the target file using the -access" function and gives notice if the 
file exists and creates a new version (if version numbers are supported by the local file system). 
Default values for protection mode and sharing options are used. 


8.2.2 ASCII 

The routines aput() are used to transmit ’text’ or ASCII format files. The ’formatted’ i/o calls fopen, 
gets, etc. are used for file access in this mode. 
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8.2.3 Binary Files 


S3 Security During File Transfer 

When the client invokes dtftp, authentication of the client is done by the login process at the remote 
host. Subsequent process spawning and/or remote login to other hosts from processes created by the 
initial client will all carry the access rights permitted to the initial client. 


8.4 Initiation of File Transfer from One Remote Node to Another 

The Network Command Language may be used at a third party location to initiate file transfer. A 
typical command would be: 

dncl> netl0::host3:filexx > c-net::fhost:newfile 

or 

dncl> mynet::host6:*dtftp filename options >> newfile 
Where filename and options are parameters to the file transfer task "dtftp". 

The effect of such a command is shown in the following diagram: 
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8.5 Initiation of Remote Procedure Upon Completion of File Transfer 

It is also possible to use the DNET Network Command Language to perform a file transfer followed 
by the execution of a remote procedure. Several alternatives are possible. 

1. Two separate commands: 

transfer the file 

dncl> bnet::host3:fi!e4 > c-net::xhost:newfi!e 

followed by 

execute the remote procedure 
dncl > c-net::xhost:*format newfile 

2 . 

One ’composite* command: 

dncl> bnet::host3:file4 > c-net::xhost: newfile | c-net::xhost:*format 

8.6 Remote Login 

8.7 Electronic Mail 

8.8 General 

DNET provides a very basic Electronic Mail facility. 


File Transfer to Mail Server 


Send or Read Mail 
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8.9 Mail Operation 

8.9.1 S tructure of DENT mail files 

The organization of DNET mail files is as follows: 

8.9.2 Sending Mail 

8.9.3 Reading Mail 

8.9.4 Mail Routing 

Routing of mail is implicit. The user sending mail must know the (DNET) destination host, network 
and user account name of the receiving party. 
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9. dnetstat - Network Status Function 


The status of Master Servers and the servers they spawn will be monitored by a program operating on 
one or more of the network hosts. Status of the Master Servers on the local network will be obtained 
using the facilities provided by the networking software native to the local network. Status of the 
servers created by the Master Servers can be obtained in the same way because the names of these 
processes can be derived from their parent. 


User wishing 
DNET Status Info 


DNET 

Host 



dnetstat - Network Status Function 
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10. Network Command Execution & Task Redirection 


The Network Command Processor is a command language processor for use in a heterogeneous 
multi-network environment. A terminal user interface and a "C" language interface to this processor 
will be provided. 

This DNET facility allows very general control of processes across the heterogeneous network and 
provides for redirection of input/output streams between files and/or processes located at arbitrary 
DNET Hosts. 

Three Software Elements are required for the Network Command Processor. 

- Network Command Interpreter (NCI) - used at the initiating node to interpret the Command Line 
(CL) entered by the user, divide this CL into separate Sub Command Lines (SCL) and pas s these 
on to the first NCS. 

— Network Command Server (NCS) - services network command which arrives from NCI or another 
NCS; provides any local service requested, including process spawning, and sends remainder of the 
SCL to the next NCS in the command chain The NCS is a DNET application server and is thus 
registered in relevant domain server tables. 

A Schematic view of the relationship between these components is shown in the figure below. The 
generic command string being executed is: 

Netl::Hostl:File X > Net2::Host2:*Proc2 > Net3::Host3:*Proc3 > Net4::Host4:File Y 

10.1 Network Command Processor Schematic 
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DNET Host 1 DNET Host 2 DNET Host 3 DNET Host 4 

(on Net 1) (on Net 2) (on Net 3) (on Net 4) 



10.2 Network Command Language 

10.2.1 Command Language Syntax 

There are two types of objects- Files and Filters. The ">" operator is used to delimit the SCL 
components of the CL. 

Filename syntax is: network_name::host_name:filename 

Taskname syntax is: network_name::host_name:*taskname(paraml, para m2 ...) 

An example command is: 

starnet::xhost:cflle > yhost:*sort > myfile 


Other examples are given below. 

When the network name or host name is not specified the local name is assumed. Spaces around the 
"> H are optional. 


10.2.2 Using The Command Language 

When filenames appear in command strings they imply the execution of file i/o servers. The network 
command: 

dac_net::vax2:david.comm > g_net::hostl:*checkp > results 

requests that the contents of a file "david.comm" on host "vax2" in the network "dac_net" be run through 
the filter checkp executed on "hostl” in the network "g_net, and the output be placed in the file 
"results" in the host on which the previous NCS was run (g_net::hostl in this case). 
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The network command: 


net_one::vax6:c-fiIe > hostl:s-cfile 

requests that the contents of a file "c-file" on host "vax6" in the network "net_one M be copied to the file 
”s-cfile M on the hostl machine on the same network. The network command: 

10.3 Network Command Interpreter 

The Network Command Interpreter is invoked as an application from the shell prompt on the local 

system. 


%) dncl 


%) dnc 

dncl> command stringl 
response to CS1 
dncl> command_string2 
response 


etc* 

After parsing the CL, the NCI module opens a dnet connection to the NCS module specified in the 
first SCL. The complete list of SCLs are passed over this connection to the NCS component. 

All interaction between NCS components and between the NCI and NCS components are via 
standardized packets. The packet header contains a length field and packet type field to describe the 
data (if any) that follows. 

The NCI module then wait for an ACKCOMP packet type to be recieved over the connection just 
established to send the CL to the first NCS module. An ERROR packet type may also be received at 
this point, and the data within the packet would be an error message generated at one of the downline 
NCS modules. 

10.3.1 Schematic of Network Command Interpreter 
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Network Command Interpreter 


User Command = 
dnc A > B > CR 



10.4 Network Command Server 

The NCS module is set up to provide for exactly one SCL. This may involve reading a file, spawning a 
filter, or creating a new output file. After the last NCS module has completed successfully, it will 
initiate an ACKCOMP packet to inform all NCS modules upline, and the initial NCI module that the 
operation was completed successfully. 

Operations at the NCS include: 

1. Wait for the NCI client or an upline NCS component to request a connection. 

2. Read the CL (one SCL at a time) from the established dnet connection. 

3. Determine SCL category 

• First SCL on the CL — read file 

• A middle SCL - filter 

• Last SCL on the CL — create output file, initiate ACKCOMP 

4. Read input data packets until EOF packet arrives 

5. Send EOF packet downline 

6. Wait for ACKCOMP packet to arrive from downline 

7. Send ACKCOMP packet upline 
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8. Close upline and downline channels 


10.4.1 Operations at Network Command S erver during File I/O 



10.4.2 Status Reporting (from last Network Command Server) 
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Datagram to Client Site 


dncl Client 
RecVing 
Report 



Last N/W 
Command 
Server 
in chain 


10.5 An Example 

An example command is: 

netl::host5:*lookup< > net2::host4:*sort > net5::hostl:filex 

The execution of this command is discussed below. 

To support the execution of network commands two types of tasks are used: network command servers 
(net com_serv) and network i/o servers (net_file_io). 


The net com_serv tasks will assist in the remote execution of network commands by accepting 
messages from other hosts* network command servers, spawning tasks as required, reading from and 
writing to other hosts, passing the data to the spawned task as "standard input" (SYS $INPUT) and 
taking "standard output"(SYS$OUTPUT), thereby allowing the spawned tasks to operate in the 
network environment without modification. 


The second type of supporting task is the net_file_io. It is used to transmit and receive files. When a 
filename appears as the only object in command component (i.e. it is not a parameter to a task), it is 
assumed that the task to be executed is net file io. 


The procedure used by a network command server to execute a network command is: 


1. Read a command line from a network command language processor, or a network command 
server 

2. After deleting that portion of the command that is being executed by the current host, send a 
copy of the command line to the host that will execute the next part of the command line 

3. Identify the first task name in the command line (scan from left) 

4. Spawn the identified task using the host that sent the command line in step 1. as the source of 
standard input to the spawned task (pass data through a mail box to the spawned task) and send 
the output from that task to the network command server on the host which will execute the next 
task in the command line. 

When the network command server controlling the last task in the command string completes, it sends 
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a termination message, with status information, to the network/host/process that initiated the 
command execution chain. 

10.6 An Example of Network Command Execution 

As described above, the network commands will be processed by distributing all or part of the 
command line to various hosts for execution. Processing will start by sending a copy of the command 
line from the network command language processor to the network command server on the system 
which will execute the first task in the command line. To execute the network command: 

netl::host5:*Iookup < > net2::host4:*sort > net5::hostl:filex 


the following processing is performed: 

1. The network command language processor sends a copy of the command line to netl host5 

2. The network command server on netl host5 will send to net2 host4 a copy of the command line 
text starting at "net2::host4". 

3. Then identify the task ’lookup" as the task to be executed. 

4. Spawn a copy of the lookup task with standard input comming from the host that sent the 
command line and standard output going to net 2 host 4. Both standard input and output streams 
pass through the mailbox shared by the lookup task and the network command server which 
spawned it. 

5. Status messages are sent to the network command processor that invoked this command 
execution. 

6. The network command server on net2 host4 will send to net5 hostl a copy of the command line 
text starting at "net5::hostl”,then 

7. identify the task "sort” as the one to be executed. 

8. Spawn a copy of the sort task with standard input being from the host which sent the command 
line and standard output to net 5 host 1. Both standard input and output streams pass through 
the mailbox shared by the sort task and the network command server which spawned it. 

9. The network command server on net 5 host 1 will read the command line and 

10. identify "filex" as a filename, therefore choose task "net_file _io H as the one to be executed. 

11. Since there is no more text in the command line there is no successor task to send the command 
line to. The network command server spawns the net_file_io task with "filex” as the output file 
and standard input being from the host which sent the command. Data from the input source is 
read and stored in the output file until an end of file causes the termination of the net_file io 
task. 

12. This causes the parent process, "ne^com^serv” to send a completion status message to the 
process that initiated the execution of this command string. 


10.7 Network Command Processor Implementation 


There are three major components in the Network Command Processor: 
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Network Command Interpreter 
Network Command Server 
Network File I/O 


The implementation of these is outlined below. 

10.8 Network Command Interpreter 

The Network Command Interpreter reads commands from users, parses, processes, and distributes 
them to the network servers on the specified hosts, messages sent to the servers that execute the 
command. 

In the design presented below the symbol used for the data flow operations is . 

"Names’ 1 refer to either files or tasks (the precedes tasknames). 

The datagrams sent to the Network Servers are produced as follows: 


1. Pointer PI is set to the start of the first name in the command. 

2. Starting at PI text is scanned, stopping at the first op code it finds, or the end of the 
command line, whichever is found first. If it finds the end of the command line a flag is set 
(see below for processing done for this). 

3. The op code is saved in 'op*. 

4. P2 is set to the start of the name following the op code. 

5. Scan as in Step 2 to the next op code. 

6. Using PI ’op* and P2 genetate the skeleton form of the message that will be sent to the host 
whose name is pointed to by PI. 

7. Set PI to the value in P2. 

8. If the "end" flag is not set go to Step 2. 

10.8.1 Additional Processing 


Additional processing of messages is required to add information about "implied" servers and 
parameters for file names and for the return of completion status. Samples of the types of messages 
that require this processing are shown below. 


Original Message 

Modified Message 

Hostl:*taskl < > Host2:*task2 
or 

Hostl:*taskl > Host2:*task2 

Prefix message with name of net_com_serv. 

Hostl:*taskl > Host2:file2 

Prefix message with name of net_com_serv. Replace file2 with 
*net file io, (create, file2) 


Network Command Execution & Task Redirection 91 










Hostl:filel > > Host2:file2 


Prefix message with name of net_com_serv. Replace file2 with 
*net_filejo, (append, file2) 


In addition to the modifications shown above, each message will be given a serial number uniquely 
identifying the command with which it is associated and the network address of the command 
interpreter to which completion status will be sent. 

10.9 Network Command Server 

The Network Command Interpreter sends messages to the various hosts specified in a network 
command. The messages contain the name of a server, the parameters to be used in processing, and 
the network address of the Network Command Server to which the completion status code should be 
sent. 

10.9,1 Implementation of the Network Command Server 

The Network Command Server listens for datagrams from any Network Command Interpreter. Upon 
receiving one it determines the name of the server being requested, the parameters to be used in the 
call to it, and the network address of the Network Command Interpreter that sent this request. 

On VMS systems the following is done: 

To obtain the name of the mailbox associated with an instance of the requested server the local Master 
Server is called. The Network Command Server then writes a message to the mailbox, requesting a 
local service connection. In this mode of operation the client (Network Command Server) provides the 
names of one input and one output mailbox to be used by the requested server for SYSSINPUT and 
SYSSOUTPUT. During the execution of the command the Network Command Server continuously 
reads from the network connection to the prior host in the command pipeline and writes to the 
SYS$INPUT mailbox. At the same time it continuously reads from the SYS$OUTPUT mailbox and 
writes to the network host on which the next task in the command pipeline is executed. 

After the completion of the command execution the Network Command Server Deassigns the 
mailboxes used in the command, keeping them for future use. The completion status code is returned 
to the originating Network Command Interpreter by sending a datagram. 

On UNIX systems the processing is as follows: 

Each server is created by the Network Command Server when needed, using the fork and exec system 
calls. In this way the standard input/output files, in this case pipes, created by the parent (the Network 
Command Server) are available to both parent and child. During the execution of the command the 
Network Command Server reads from the network connection to the prior host in the command 
pipeline and writes to the standard input of the child. At the same time it reads from the standard 
output of the child and writes to the network host on which the next task in the command pipeline is 
executed. 


The completion status code is returned to the originating Network Command Interpreter by sending a 
datagram. 

10.10 Network File I/O 


Network File I/O is a server that is used to read and write files on the local host to and from remote 
hosts. It assists in transmitting input and output data across network connections that support 
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command pipes. 


The arguments to Network File I/O are 

- mode (append or create) 

— filename 
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1 1 . Presentation Layer Services 


11.1 XDR 

dn xdr.c 
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12. DNET Error Handling 


DNET Basic I/O Library functions return a non-selective error code if an error is detected during their 
operation. These errors are defined in the header file ../dnet/common/dnet_errno.h 

Errors detected by the DNET code are identified in the variable dnet_errno: 
dnet errno = XXXXX; 


An error function, dneterror ("string"), is then optionally called where string is an optional, user 
provided informative message. dnet_error provides detailed information on conditions when the error 
was detected including a stack trace. 

dnet_error(*error_string) 
char * error_string; 


Detailed error codes are provided in the programmer reference manual. 
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13. Routing 


13.0. 1 get jpath. 

13.0. 2 loadjnyjiame 

13.0. 3 load net Jable 

The router selects the host/process to which the datagram will be transmitted next. 
get_path(); 

path = get_path(srcjiet,src_host,dest_net,dest_host,dest_process,numhops); 

src_net is the network in which the destination host is located 
src_host is the destination host 

dest_net is the network in which the destination host is located 
dest_host is the destination host 
dest_process is the destination process 

numhops - number of hops from current location to destination 

13.1 Router Operation 

The paths to hosts in the local network are direct connections. For paths to hosts in other networks a 
dynamic router is used. A hierarchical routing table is used to determine the host to which the 
datagram should be sent next. The entries in the routing table are updated by exchange of 
connectionless datagrams between DNET gateways and individual DNET hosts. 

In the future the router may be enhanced to include searching for alternate paths and servers if the 
standard search fails to satisfy the request. The second search could extend into other networks in 
requests for generic servers that need not be executed in a specific network or host. Extended searches 
will provide automatic alternate routing, load sharing, and backup services for use when failures in 
hardware or software reduce the availability of facilities. 

The datagram header contains three fields which are used in routing as indicated below: 
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dglen [ chan ] type | numhop Src j Rel Src | Next | Dest [ Rcpt 

| Seq# | Msg | 


- - " ^ " " 

7 ^ 
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/ "* ^ 

1 N ^ 

" - 

Src Net | Src Host | Src Host 

Rel Net | Rel Host | Rel Proc 

Next Net | Next Host | Next Proc 

-Dest Net | Dest Host | Dest Host 
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typedef struct { 

short dglen; /* The total length of the datagram, excluding 
this field */ 

short chan; /* The channel number that is being used */ 
short type; /* A code for the datagram type - Connectionless, 

Virtual Circuit or Signal */ 

short hopnum; /* The curent hop number- to catch circular routing*/ 

char srcnet; /* The DNET code for the src host’s network name */ 
short srchost; /* The DNET code for the src host’s host name */ 
char *srcproc; /* The name of the process to be used on the src host */ 

char rel_srcnet; /* The DNET code for relative 
src host’s network name */ 

short rel_srchost; /* The DNET code for the src host’s host name */ 
char *rel_srcproc; /* The name of process to be used on the src host */ 

char nextnet; /* Next DNET network to be reached */ 
short nexthost; /* Next DNET host (on nextnet) */ 
char *nextproc; /* Process to be contacted on ’nexthost’ */ 

char destnet; /* The DNET code for the dest host’s network name */ 
short desthost; /* The DNET code for the dest host’s host name */ 
char *destproc; /* The name of the process to be used on the dest host */ 
char receipt; /* Return Receipt Request = 0 no receipt 

1 receipt requested 

char *sequence# /* PID and datagram sequence number */ 

char *msg; /* The data to be sent */ 

} DATAGRAM; 


A typical routing table is shown below: 


DNET Local Routing Table 

Destination Net 

Next (Gateway) Host 

Next Process 

Datagram Protocol 

dnettl 

- 

- 

udp 

spa net 

dacvax 

drelaytd 

udp 

st a met 

dacvax 

drelaytd 

udp 

Net X 

HostY 

drelaytX 

udp 

• 

• 

• 

- 






13.2 Routing Example 


The route generated for a typical datagram is shown in the following diagram: 
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Server SV X 


In this example client CL_X on DNET host D2 wishes to conduct a session with server SV_X on 
DNET host T2. 

The router on host D2 has the following routing table available: 



The router on host D4 has the following routing table available: 
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DNET Local Routing Table - (Gateway) Host D4 

Destination Net 

Next (Gateway) Host 

Next Process 

Datagram Protocol 

spanet 

NULL 

NULL 

dec 

dnettl 

dacvax 

drelaytd 

udp 

st a met 

iaf 

delaydt 

dec 

- 

- 

■ 

- 

- 

- 

- 

- 

- 

- 

- 

• 

- 

- 

• 

• 


133 Routing Table Updates 

Initially, routing table updates will be bandied in a manual fashion. Exa min ation of a method for 
automatic updates for these tables will be considered as time allows. 
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ASS_DG(3I) 


DNET 


ASS_DG(3I) 


NAME 


ass_dg - assemble a dnet datagram. 

SYNOPSIS 

#include "dnet" 

int ass_dg(udg, ddg) 
struct udg *udg; 
char *ddg; 

DESCRIPTION 

The ass_dg internal library routine takes the contents of the udg structure and assembles a 
standard dnet datagram into the ddg buffer. 

This function is used for purposes of preparing the user datagram to go over a network. Integer 
conversions are performed here as necessary. This function is only called by the per protocol 
dgs components. 

SEE ALSO 

dass_dg(3I) 

RETURN VALUE 

The ass_dg routine will return the size in bytes of the assembled datagram if successful. If an 
error condition exists, then the return value will be -1 and the external variable dnet errno will 
hold the error value. 

ERRORS 

The call will not currently return in error. 
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CHECK_MYNET(3I) 


DNET 


CHECK_MYNET(3I) 


NAME 


check_mynet - validate the name of default network 
SYNOPSIS 

#include "dnet.h" 

int check_mynet() 

DESCRIPTION 

This routine checks the name of the default network (retrieved by load_my nmae(3I)) against 
entries in the tbls.net table (loaded by load_net table(3I)) to insure the the default network is 
truly defined. 

This routine is currently only called from the dn_init(3U) routine. 

SEE ALSO 

dn_init(3U), load_my_name(3I), load_net_table(3I) 

RETURN VALUE 

The routine returns a value of zero on success, and -1 to indicate an error. 

ERRORS 

The call fails if: 

[D_INTERN] The default network name could not be found in the tbls.net table. This would 
indicate an administrative error. 
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DASS_DG(3I) 


DNET 


DASS_DG(3I) 


NAME 

dass_dg - dissasemble a received dnet datagram. 

SYNOPSIS 

#include "dnet.h" 

int dass_dg(ddg, udg) 
struct udgbuf *ddg; 
struct udg *udg; 

DESCRIPTION 

This routine dissasembles a datagram received from the network into the structure used bv dnet 
user programs and the dgms. 

The per protocol dgs components are the only components that need to call this routine. 

Network integer conversions are performed for the header information in this routine as 
needed. 

SEE ALSO 

ass_dg(3I) 

RETURN VALUE 

The routine will return a value of 0 on success and a value of -1 to indicate an error condition. 
ERRORS 

This routine will not curr jntly return in error. 
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DBCOPY(3I) 


DNET 


DBCOPY(3I) 


NAME 


dbcopy - binary copy 
SYNOPSIS 

int dbcopy(frombuf, tobuf, len) 
char *frombuf; 
char *tobuf; 
int len; 

DESCRIPTION 

The dbcopy library routine provides a binary copy of data from one location in memory to 
another. The first argument (frombuf) is the address of the source buffer. The second 
argument (tobuf determines the location to copy to (destination buffer), and the third argument 
(len) specifies the number of bytes to be copied. 

SEE ALSO 

dbzero(3I) 

RETURN VALUE 

This function returns an undefined value. This value should not be tested. 

BUGS 

This function returns an undefined value. This value should never be tested. 
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DBZERO(3I) 


DNET 


DBZERO(3I) 


NAME 


dbzero - zero fill a buffer 
SYNOPSIS 

int dbzero(buf, buflen) 
char *buf; 
int buflen; 

DESCRIPTION 

The dbzero library routine provides a standard mechanism for zero filling a given buffer of 
given length. The fisrt argument is the address of the buffer, and the second argument specifies 
the number of bytes that are to be zero filled. 

SEE ALSO 

dbcopy(3I) 

RETURN VALUE 

This library routine always returns an undefined value, but never fails. 

BUGS 

This library routine returns an undefined value, no test on the value should be made. 
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DG_GET_NEXT_HOP(3I) 


DNET 


DG_GET_NEXT_HOP(3I) 


NAME 


d S_8 e I_ nex t_hop - set ne::t node in user datagram structure 
SYNOPSIS 

#include "dnet.h" 


int dg_get_next_hop(udg) 
struct udg *udg; 

DESCRIPTION 


is routine will take the values passed in the user datagram structure and will determine the 
next hop value" for that datagram. The value of the next hop will be placed in the next.net 
“° St ’ a i nd , n i ext proc f ields of the ud S structure. Tht values placed in the next node fields 
will differ slightly according to wether the next hop is a process on the existing machine, or is 
the address of another host on a network directly linked to the current machine. 

The value of proc always represents the process to send the message containing the datagram to 
on the current machine. In the case of a datagram arriving at the destination, this represents a 
user processes bound to process name and may be looked up in the ADGUT. The net and host 
entries will be set to the same value in the destination node. 

In the case of a datagram arriving at a gateway, the process name set represents the bound to 
process name of the per protocol DGS component that runs the network over which the next 
op host is connected to. The net and host names represent the place that the per protocol DGS 
component is to send the datagram. The net name is required as the DGS component may be 
responsible for more than one network of a given type. 

RETURN VALUE 

This routine will return a value of 0 on success and a -1 when 
an error condition exists. 

ERRORS 

The call fails if: 

[D_NOPATH] The network passed in the user datagram structure could not be resolved in 
the current host’s routing table. 

CAVEATS 

This routine is defined internally within the dgms component and therefore is inaccessable to 
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DISASSEMBLER!) 


DNET 


DISASSEMBLER!) 


NAME 


disassemble - disassemble a "datagram" for connection services 
SYNOPSIS 

#include "dnet.h 11 

void disassemble(buf, dg) 
char *buf; 

struct datagram *dg; 

DESCRIPTION 

This user library routine (used only with the connection oriented services) disassembles a 
datagram created by one of the following user library routines: 

• dn_makedg(3U) 

• dn_makepvc(3U) 

• dn_makesignal(3U) 

The datagram is disassembled into a datagram structure of the following form: 

struct datagram 

{ 

short dglen; 
int stream; 
short type; 
short numhops; 
short pathlen; 
char *path; 
char *msg; 

}; 

SEE ALSO 

dn_makedg(3U), dn_mal:epvc(3U), dn_makesignal(3U) 
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DN_ALLOC(3I) 


DNET 


DN_ALLOC(3I) 


NAME 


dn_alloc - dynamically allocate memory for dnet structures 
SYNOPSIS 

#include "dnet.h" 

char *dn_alloc(s_token, ctoken, size, addr) 

int stoken; 

int c token; 

unsigned *size; 

char *addr; 

DESCRIPTION 

The dn_alloc internal library routine (should be implemented for the user library also) 
dynamically allocates memory for the dnet structures to be used by programs. These routines 
not only encourage the efficient usage of memory, but also provide for portability of programs if 
the definition of the structure is modified. If these routines are used, then the template of the 
structre should not be redefined, and fields should be referenced through the field names 
provided in the system definition of the structure. 

The following structures may be allocated using this routines: 

DGMS_MSG This will allocate space that may be accessed through the dgms msg 
structure. 

DN UDG This will allocate space that may be accessed through the udg structure. 

DN SVMSG This structure token is only valid and compiled on a Unix System V and will 
result in a D BADARG error condition if use is attempted on any other 
system. This allocates space necessary for the msgbuf structure used in 
System V message queues. 

The c token parameter must specify one of the following command tokens: 

DN_ALLOC This is used to initially allocate the structure. The addr field is ignored. 

DNREALLOC This is used to reallocate the size of an existing structure allocated using the 
DNALLOC command. The addr field must reference the address of a valid 
structure allocated using the DN ALLOC command. 

DN DALLOC This command is used to deallocate, or free up the space allocated for the 
structure, after the structure is of no use. As the amount of dynamically 
allocated memory increases, the efficiency at which more memory is allocated 
decreases. 

The size parameter is a pointer to an unsigned value. This value is read by dn alloc to 
determine the requested size of the buffer field within the structure being allocated. If The value 
is zero, then dn_alloc will allocate the maximum allowable buffer for that particular structure. 
The dn_alloc routine will return in the location specified by size the size of the entire allocated 
structure. The size of the header may be determined by subtracting the number of requested 
buffer bytes (if non-zero) from the value set after the dn_alloc call. If the size is not initi alize d 
to a valid value, the program will behave unpredictably. 

The addr parameter is only meaningful when used with the DN_REALLOC or DN DALLOC 
commond token. In these cases the address should be the location in memory of a dnet 
structure previuosly allocated with dn alloc. 
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DN_ALLOC(3I) 


DNET 


DN_ALLOC(3I) 


RETURN VALUE 

The routine will either return the memory location of the newly allocated structure, or a NULL 
value indicating an error. 

The DN_DALLOC command will always return a NULL pointer. 

ERRORS 

The call fails if: 

[D SYSERR] A system error has ocurred, check the errno variable to determine what the 
system error was. 

[D_BADARG] An unknown structure token was passed. 

[D_BADARG] An unknown command token was passed. 

P_ BADARG 1 The ccmmand token was either DN_REALLOC , or DNDALLOC and the 
addr field was 0. 

[DJvlSGTB] The size argument passed with the DGMS_MSG or DNSVMSG structure 
token exceeded the maximum allowable size for that structure. 

[DJDGTB] The size argument passed with the DN_UDG structure token would exceed the 
maximum allowable datagram size. 

BUGS 


This call is implemented on top of the malloc library routines which are ambiguos as to the 
source of error. Therefor, the dn_alloc routine may incorrectly report a system error when one 
has not actually occurred. 
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DNJNITPERM(3I) 


DNET 


DN INITPERM(3I) 


NAME 


dn_initperm - Establish and bind an endpoint for communication 
SYNOPSIS 

int tcpjnitperm(service, backlog) 
char *service; 
int backlog; 


int decnet_initperm(service, backlog, pauxchan) 
char ^service; 
int backlog; 
int ♦pauxchan; 

DESCRIPTION 


The dn_initperm routines establishes an endpoint for communication over either a TCP/IPC or 
DECnet provider, binds to the port number specified by service, and specifies that up to 
backlog connection requests may be outstanding on the established endpoint. In the 
decnet imtperm routine, the pauxchan points to the location where the file descriptor will be 
placed for the mailbox associated with the network channel. This is needed to handle multiple 
inbound requests on VMS. v 

request'' * ^ *** UP ** endpoint and wil1 not block waiting for a connection 

The service argument is a character string that has either been defined as being a well known 
service (in /etc/services on UNIX machines) or is an ASCII representation of an integer value 
in which case the value will be used directly as the TCP port to bind to. 

SEE ALSO 

dn_initperm(3U) 

RETURN VALUE 


The call returns a valid file descriptor to the endpoint on success or a -1 to indicate an error. 

ERRORS 

The call fails if: 

[D_SYSERR] A system error has occurred, check the global variable ermo (on UNIX 
machines) to determine the cause. (UNIX ONLY) 

[D INTR] A signal was caught while attempting to establish the endpoint. No endpoint will 
be established in this case. (UNIX ONLY) 

[D_NODNETSRV] The service name specified could not be found in the definition of 
servers (/etc/services on UNIX). (UNIX ONLY) 

BUGS 


The decnet initperm routine does not currently set any indication for cause of error 
standard VMS error reporting routines should be consulted in when using this routine. 


The 
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DN_MAKEDG(3I) DNET DN_MAKEDG(3I) 


NAME 

dn_makedg - assemble a .)G_CALLBACK datagram 
SYNOPSIS 

void dn_makedg(buf, channel, numhops, path, msg) 

char *buf; 

int channel; 

int numhops; 

char *path; 

char *msg; 

DESCRIPTION 

This internal library routine assembles a DG_CALLBACK datagram, used exclusively by the 
connection oriented service, given the channel number, the number of hops, the path, and 
message. The contents of the assembled "datagram" are placed into the buf buffer. The 
assembled datagram resembles: 

dglen | channel | type = D ^CALLBACK | numhops | pathlen | path | msg 

The path element is composed of the following. (Sometimes the next and destination hops are 
the same so the three next elements are eliminated): 

thisnet | thishost | thisproc | nextnet | nexthost | nextproc | destnet | desthost | destproc 
SEE ALSO 

dn_makepvc(3I), dn_makesignal(3I) 
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DN_MAKEPVC(3I) 


DNET 


DN_MAKEPVC(3I) 


NAME 


dn makepvc - assemble a DGSTREAM datagram 
SYNOPSIS 

void dn_makepvc(buf, channel, msg) 
char *buf; 
int channel; 
char *msg; 

DESCRIPTION 

This internal library routine creates a DGSTREAM "datagram” (used only by the connection 
oriented services) given i channel and message. The assembled "datagram" is placed into the 
buffer (buf). The datagram looks similar to: 

dgjen | channel | type = DGSTREAM | msg 

SEE ALSO 

dn_makesignal(3I), dn_makedg(3I) 
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DN_MAKESIGNAL(3I) 


DNET 


DN_MAKESIGNAL(3I) 


NAME 


dn_makesignal - make a .'3GSIGNAL datagram 
SYNOPSIS 

void dn_makesignal(buf, channel, msg) 
char *buf; 
int channel; 
char *msg; 

DESCRIPTION 

This internal library routine assembles a DG SIGNAL "catagram" (used only by the connection 
oriented services) given a channel and message. The assembled "datagram" is placed into the 
buffer (buf). The assembled "datagram” looks similar to the following: 

dg Jen | channel | type = DG_S IGNAL | msg 

NOTE: For now, this is identical to dn_makepvc(3I) except that the datagram type is 
DG_SIGNAL. Eventually, this should assemble something that looks more like a 
DG DATAGRAM datagram. 

SEE ALSO 

dn_makepvc(3I), dn_maledg(3I) 
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NAME 


dnet_error - print dnet stack dump and error description 
SYNOPSIS 

#include "dnet.h" 

void dnet_error(user_message) 
char *user_message; 

DESCRIPTION 

The dneterror library routine prints out a dnet stack dump and a descriptive error message 
about the dnet error thit just occurred. If the dnet error indicates a system error, then a 
descriptive message of the system errror which just occurred will also be displayed. 

On top of the error display and stack dump, the message pointed to by the first argument 
(user_message) will be displayed. 

BUGS 


The descriptive error messages being written are dependant upoon the underlying services 
setting the dnet_errno variable (see dnet errno.h). In the connection services and on the VMS 
machines, this variable is not reliably set. 
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NAME 


get_firsthop - get source lode description from path strin r 
SYNOPSIS 

#include "dnet.h" 

int get_firsthop(path, fir>thop) 

char *path; /* Returned by get_path(3I) */ 

HOPFIELD *firsthop;/fP 

DESCRIPTION 

The get_firsthop routine will set the value of firsthop to the source node description according 
to the values in the path string. The gct_path(3I) routine may be used to extract routing 
information, which can then be broken out by this routine, get nexthop(3I) and 
get_lasthop(3I). - v ' 

SEE ALSO 

get_path(3I), get_nexthop(3I), get_lasthop(3I) 

RETURN VALUE 

The return value of get_firsthop is undefined. 

BUGS 


The return value of this routine is undefined and should be ignored. 
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NAME 


get_lasthop - get destination node from path string 
SYNOPSIS 

/D#include "dnet.h" 

int getlasthopfpath, numhops, desthop) 
char *path; 
int numhops; 

HOPFIELD *desthop; 

DESCRIPTION 

This routine extracts the destination node string from the path string. The path string can be set 
using the get_path(3I) routine. 

If numhops is a non zero value, then this routine will grab the destination node description from 
the third section of the path string. If numhops is a zero value, then it is assumed that the 
destination node is being determined on the destination machine. The path string will then only 
contain two sections, ana the destination node description from the second section of the path 
string. 

SEE ALSO 

get_path(3I), get_firsthop(3I), get_nexthop(3I) 

RETURN VALUE 

The return value is undefined for this routine. 

BUGS 


This routine currently returns an undefined integer value. It should be ignored. 
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NAME 


get_nexthop - get next node description from path string 
SYNOPSIS 

#include "dnet.h" 

int get_nexthop(path, ne?:thop) 
char *path; 

HOPFIELD *nexthop; 

DESCRIPTION 

This routine will extract the next node description string from the path string. The path string is 
set by the get_path(3I) routine. 

This routine along with get_firsthop(3I) and getJasthop(3I) make up a set of routines for 
extracting node descriptions from the path string. Because the path string may vary depending 
upon the machine it is on, these routines should be used to extract the node descriptions rather 
than accessing the path string directly. 

SEE ALSO 

get_path(3I), get_firsthop(3I), get _lasthop(3I) 

RETURN VALUE 

This routine currently returns an undefined integer. 

BUGS 

This routine currently returns an undefined integer value. It should be ignored. 
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NAME 


get_path - low level dnet /outing function 
SYNOPSIS 

#include "dnet.h" 

char *get_path (source, destnet, desthost, destproc, numhops) 

struct nethost_entry ^source; 

char *destnet; 

char *desthost; 

char *destproc; 

int *numhops; 

DESCRIPTION 

This internal library routine provides the low level dnet routing service for dnet components. 
Given the source and destination networks, hosts, and processes, this routine determines wherre 
the next hop is. If the source and destination networks are the same, a two part path is 
assembled, aconsisting of the following: 

thisnet | thishost | thisproc | destnet | desthost | destproc 

In that case, a value of 0 s placed in numhops. 

If the source and destination networks are different, the router looks in the network routing 
table (loaded into memory by dn_init(3I)) for an entry wherre the source and destination 
networks match the source and destination networks passed to this routine. If a match is found, 
a path is returned that looks similar to: 

thisnet | thishost | thisproc | nextnet | nexthost | nextproc | destnet | desthost | destproc 
A value of 1 is placed into numhops to indicate this type of path. 

SEE ALSO 

get_firsthop(3I), get_nexthop(3I), get_lasthop(3I) 

RETURN VALUE 

A valid character pointer is returned on success, and a NULL pointer is returned to indicate an 
error. 
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NAME 


ipcclose - close an ipc mechanism 

SYNOPSIS 

int ipcclose(ipcid) 
int ipcid; 

DESCRIPTION 

The ipcclose internal library function removes the calling process’s access to the ipc mechanism 
identified by ipcid. Any later access to that ipcid will be invalid. 

If the mechanism being c osed was accessed by the user using the DBIND flag in the ipcget(3I) 
routine, then the mechanism will be removed from the system. If the D_BIND flag was not 
specified, then the mechanism will remain in the system until the binding peer issues the 
ipcclose(3I) call. Even if the mechanism remains intact, the user will still not be able to access 
after the ipcclose. 

SEE ALSO 

ipcget(3I) 

RETURN VALUE 

Upon successful completion, the function will return a value of 0. If an error occurred, then the 
function will return a value of -1 and will set the variable dnet_errno to indicate the error 
condition. 

ERRORS 

The call fails if: 

[D_SYSERR] A system error has occurred. Check the global variable errno. 
(D_BADARG]The ipcid passed was invalid. 

[D_EPERM] Write permission is denied on the ipc directory, or search permission to the 
ipc directory is denied. This indicates that permissions have been changed 
since the time that ipeget was called. 

[D_NODNET] The ipc directory no longer exists. 

[D_NOEXIST]The ipc mechanism has already been removed. This usually means someone 
has manually removed the file node. 

CAVEATS 

If ipcid is valid, the ipc mechanism will be closed by this routine even if an error occurrs. 
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NAME 


ipcget - establish and/or gain access to an IPC mechanism 
SYNOPSIS 

#include "dnet.h" 

int ipcget(name, flags) 
struct dnetjpcname *nanie; 
int flags; 

DESCRIPTION 


The ipcget library routine is used to establish and/or gain access to a mechanism for 
interprocess communiction. 

The following is the template definition for the dnetjpcname structure: 

struct dnetjpcname 

{ 

char nair.e[D MAXPATHNAME]; 
unsigned msgsize; 
unsigned mqueuesize; 

}; 

The name field represen's a string value that will be used to determine peers in a conversation. 
The name chosen may not contain the forward slash character. 

The msgsize field represents an attempt at negotiation between the user process and dnet for 
determining the maximum size of message that may be passed through. If the icpget call 
succeeds, then dnet guarantees that messages of that size or smaller will not be truncated. The 
ipcget call will fail if the underlying IPC mechansisms are not capable of handling a message of 
the size requested. 

The mqueuesize argument is used to request that dnet attempt to allocate enough space to 
allow mqueuesize number of messages of msgsize to be sent to the queue without ever blocking. 
This is infeasible in most environments because of sharing of buffering space with other 
processes, but can be used to warn dnet of the expected activity for a particular user. Future 
releases of dnet may actually take back allocated space if it is needed for other users. 

An integer (ipcid) will be returned on successful compleiion which must be used in future ralU 
to the established IPC mechanism. 


The following flags may be set: 


D BIND 


D CONNECT 


D GLOBAL 


S pecifies that name is to be used to identify what incoming datagrams 
are to be received at this endpoint. Only one process is allowed to bind 
to a given name at a time. Either the D_BIND, or the D CONNECT 
flag must be specified. 

Specifies the address (name) to which all datagrams leaving via this IPC 
mechanism are to be sent. This flag is mutually exclusive with respect 
to D BIND. At least one of these mutually exclusive flags 
(D_CONNECT, D_BIND) must be specified in the flags parameter. 

This flag is only meaningful when used in a VMS environment in 
combination with the DBIND flag. The effect of this flag is to 
advertise the name of the ipc mechanism in the system table, rather 
than just the job table. This flag will cause the call to fail if the calling 
process does not have SYSNAM privilege. 
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SEE ALSO 

ipcsnd(3I), ipcrcv(3I), ipcclose(3I) 

RETURN VALUE 

The function call will return a positive number representing a valid ipcid, or will return a -1 
indicating an error and the external variable dnet_errno will be set to the error code. 

ERRORS 

The call fails if: 


[D_SYSERR] 

A system error has occurred. Check the global variable errno. 

[D_BADNM] 

The name was either determined to have a length of zero, or the length 
cf the name was longer than the system imposed maximum (see 
D MAXPNAME in dg.h). All names are assumed to be null 
terminated string values. 

[D_BADMN] 

The name contained the forward slash (/) character. 

[D_BADARG] 

Both the D_BIND and D_CONNECT flags were specified. 

[D_AEXIST] 

The D BIND flag was set and another process was already bound to 
the address in name- > name. 

[DNOEXIST] 

The D_CONNECT flag was set and there was no process bound to the 
given name. 

[D_NOSRSC] 

There are currently not enough system resources available to provide 
for another IPC mechanism at this time. The call may succeed at a 
later time. 

[D_NOSRSC] 

You have too many ipc mechanisms active. You will need to perform 
an ipcclose(3I) before you issue another ipcget(3I). 

[D_QUOTA] 

w our process has the maximum number of file descriptors already in 
i se. 

[D_NODNET] 

1 he error that occurred would indicate that the proper dnet 
components were not started up, or were not started up properly. One 
or more of the followin indications were found: 


• A component of the dnet assembled absolute pathname for the IPC 
mechanism was determined to not be a directory. This is indicative 
of absence of the dnet temporary directory from this machines file 
hierarchy. 


• If the current system is Unix System V, the error may have resulted 
from the dnet message queue(s) not existing. 

[DEPERM] 

Search permission of a component of the dnet temporary directory was 
denied the calling process, or write permission to the dnet temporary 
directory itself was denied. 

[D_EPERM] 

If the current system is Unix System V, this error may have occurred 
from lack of permission to the message queue(s). 

[DEPERM] 

If the current system is VMS, then the user may not have permission to 
create mailboxes. 

[DINTR] 

- 'he system call was interrupted by the receipt of a signal before it could 
be completed. 
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BUGS 


None of the size fields within the dnet ipcname structure are currently supported or checked. 
This was provided for VMS implementations where t ie IPC queueing space is explicately 
allocated for each mecha lism. 
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NAME 


ipcrcv - receive an ipc message 
SYNOPSIS 

#include "dnet.h" 


int ipcrcv(ipcid, msg, msglen, flag) 

int ipcid; 

char *msg; 

int msglen; 

int flag; 

DESCRIPTION 

The ipcid argument is the integer handle returned from a successful ipeget routine. 

The ipcrcv function call allows a process to receive an incoming message on the specified ipcid. 
A blocking read is performed unless the D_NOWAIT flag has been set. 

The value in msg is an address of a character array where the message will be placed. No more 
than msglen characters will be read. Any extra characters will be truncated. 

SEE ALSO 

ipcsnd(3I) 

RETURN VALUE 


Upon successful completion, the function will return a value representing the number of 
characters received. If an error occurred, the value returned will be -1 and the variable 
dnet_errno will be set to indicate the specific error condition. 

ERRORS 


The call fails if: 
[DSYSERR] 
[D_BADARG] 

[D_BADARG] 

[D_NOMSG] 

[D_EPERM] 

[DJMOEXIST] 


[DINTR] 


BUGS 


A system error has occurred. Check the global variable errno. 

The ipcid passed was zero or did not reference a valid dnet ipc 
mechanism. 

The specified buffer length was less than one. 

The D_NOWAIT flag was set and no messages were waiting to be read. 

Read permission on the underlying IPC mechanism was denied to the 
calling user. 

The peer reset it's connection. The ipcrcv routine will issue an 
ipcclose(3I) on this ipcid to invalidate it for you. On System V 
machines, this actually means that the dgms component reset the entire 
ipc medium. 

A signal was caught while attempting to read from the ipc mechanism. 
No message was read in. 


The D_NOWAIT flag requires a system call after receiving a message in the BSD environment. 
This opens up the possibility of a signal being posted after a successful read. This situation will 
cause a D_INTR error to be specified and the ipcrcv call will appear to fail. If the D_INTR 
message is set, check to see if the message was actually read, and if so, reissue another non- 
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blocking read to reset the socket endpoint properly. 
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NAME 


ipcsnd - send a message \ia a dnet IPC mechanism 
SYNOPSIS 

int ipcsnd(ipcid, msg, msglen, flags) 

int ipcid; 

char *msg; 

int msglen; 

int flags; 

DESCRIPTION 

The ipcsnd function call allows a process to send a message out an IPC mechanism created with 
the ipcget library routine. 

The only flag value currently supported is the D_NOWAIT flag which will insure that the calling 
procedure will not block on back pressure from the underlying IPC mechanism. 

SEE ALSO 

ipcrcv(3I) 

RETURN VALUE 


Upon successful completion, the ipcsnd function call will return a value of 0. If an error 
occurred, a value of -1 will be returned and the dnet_eirno variable will be set to indicate the 
error code. 

ERRORS 


The call fails if: 


[D_SYSERR] A system error has occurred. Check the global variable errno. 

[D_WOULDBLOCK] The D_NOWAIT flag was set and sending the message at this time 
would cause the process to block waiting for the underlying mechanism to 
release back pressure. 

[D_BADARG] The ipcid value passed was either zero, was a negative number, or did not 
represent a valid dnet IPC mechanism. 


[D BADARG] The ipcid passed represents an IPC mechanism created with D BIND, and 
therefore cannot be used with ipcsnd. 

[^_®ADARG] The value of umsglen was determined to be less than one or greater than the 
maximum allowable message size (D_MAX_IPC_MSG_SIZE in dnet_ipc.h). 

[D_NOEXIST] The peer reset it’s connection. The ipcsnd routine will issue a ipcdose(3I) for 
your process. 


CAVEATS 


Unix System V implementations attempt to dynamically allocate memory space for sending 
messages when they are called from within a dnet user program. This may result in a system 
error occurring from temporary lack of memory space v/hich may be available at a later time. 
The expected results would be that dnet errno would be set to D_SYSERR, and errno would 
be set to EAGAIN. The current implementation provides no explicit or guaranteed method for 
determining this condition. 

BUGS 


No explicit and guaranteed indication of temporary lack of dynamically allocatable memory 
space is provided by dnet. 
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NAME 


is_error - print error message if system call return value indicates error 
SYNOPSIS 

int is_error(retvaI, errmsg) 
int retval; 

char *errmsg; /* Message to print if error occurred */ 

DESCRIPTION 

This internal library routine is meant to be called after a system call. If the value returned by 
the system call (retval) indicates an error, the the errmsg is displayed. 

NOTE: 

This function has probably outlived its usefullness. The original intent was to get a handle on 
errors returned on the VAX. Some system calls (those implemented by Wollongong) return an 
error value but fail to set errno so that you can’t learn anything by calling perror(). Instead, 
another external variable, uerrno, was set. This function was needed to get the value of uerrno 
so we coulde ook it up in the errno. h file manually. 

SEE ALSO 

dnet_error(3U) 

RETURN VALUE 

This routine returns a vlue of 0 if retval is not negative, and a 1 if it is. 
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NAME 


load_my_name - determine the name of this host 
SYNOPSIS 

#include "dnet.h" 

int load my name() 

DESCRIPTION 

This internal library routine loads the entry from the myname table into the myname structure. 
The mynamejable array is defined in the dnet.h header file and is of type struct nethost^entry. 
The nethost_entry structure is defined as follows: 

struct nethostentry 

{ 

char netname[MAXNAMESIZE]; 
char hostname [MAXNAMESIZE]; 

}; 

The loadjnyjiame routine determines these values from the tbls.myname file in the dnet home 
directory. 

If your module contains a main function definition, then the following line must be in your code 
before the inclusion of dr et.h: 

#define MAINPROGRAM 

SEE ALSO 

dnjnit(3U), Ioadjiet _table(31) 

RETURN VALUE 

This routine returns a zero on success and a -1 on failure. 

ERRORS 

The call fails if: 

[D_NOSYSFILE] The tlbs.myname file could not be found in the dnet home directory, or 
was in an invalid format. 

[D_SYNERR] More than one non-commented entry v as found in the tbls. myname file. 
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NAME 


load_net_table - load routing table into memory 
SYNOPSIS 

#include "dnet.h" 

int load_net_table() 

DESCRIPTION 

This internal library routine is used to load the current host’s routing table into memory for 
quicker access and use by future routing functions. 

The table is loaded into a structure array defined in dnet.h and named net route table. The 
structure type is netrout ;_entry and is defined as follows: 

struct net_route_entry 

{ 

char srcnet[MAXNAMESIZE]; 
char destnet [M AXNAM ESIZE] ; 
char gateway [MAXNAMESIZE]; 
char dgsprocfMAXNAMESIZE]; 

}; 

The table is initialized from the tbls.net file in the dnet home directory. 

If your module contains a main function definition, then you will need to add the following line 
above the inclusion of dnet.h: 

#define MAINPROGRAM 

SEE ALSO 

dn_init(3U), load_my_name(3I) 

RETURN VALUE 

This routine returns a zeio on success and a -1 on failure. 

ERRORS 

The call fails if: 

[D NOSYSFILE] The tbls.net file was not found in the dnet directory, or read permission 
was denied. 

[D_NOSRSC] The tbls.net file contained more records than were defined for the internal 
table. Look at the value of MAXTBLSIZE in the dnet.h header file. 

[D_SYNERR] A record was found in the tbls.net table that was determined to have the 
wrong number of fields. 
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NAME 


makeipc - administrative creation of an IPC medium 
SYNOPSIS 

#include "dnet.h" 

int makeipcO 

int jnakeipc(sv_msg_ke 3 ', ipcdir, flags) 
int sv_msg_key; 
char ♦ipcdir; 
int flags; 

DESCRIPTION 

These library routines provides for the administrative creation and general access of a dnet IPC 
medium. The creation of an IPC medium (not to be confused with creation of an IPC 
mechanism as described in ipcget) allows creation of a private "area” within the means of inter 
process communication of the operating system. The intention is to avoid collisions with 
unrelated processes using inter process communication. The creation of a private area differs 
according to the operating system. 

On all UNIX machines, the UNIX filename is supported for addressing a particular IPC 
mechanism. To facilitate this, an ipc directory is used to place all addresses (only filenames are 
supported, explicate pathnames will cause an error on ipcget). If, in addition, the machine hosts 
a System V operating system, a System V message queue is also required. In a VMS 
environment, these routines are effectively empty functions. 

All IPC routines require that the IPC medium be accessed by all processes wishing to use it. In 
addition, an administrative process needs to create it before any other processes attempt to 
access it. The flags parameter allows the _makeipc row ine to be issued for creation by using 
D_CREAT | DJEXCL. The makeipc routine calls _makeipc with the flags set in this fashion. 
If jnakeipc is called with only the D_CREAT flag specified, then the removeipc (or 
removeipc) will always return successfully without removing the medium. Processes other than 
the administrative process should attempt to "access" the IPC medium by setting the flag values 
to 0. The call will fail in this case if the IPC has not been created. 

The first two parameters to the jnakeipc routine allow the processes to choose the IPC 
directory and System V message queue key value (only meaningful on a System V machine). 
These parameters allow for avoidance of collisions with other, unrelated processes using the 
interprocess communication means for a particular machine. In addition, the proper placing of 
the IPC directory may also provide additional security inberant within the UNIX filestore. 

SEE ALSO 

ipcget(3I), removeipc(3I) 

RETURN VALUE 

Upon successful completion, the function will return the value of the msqid for the System V 
message queue created, or a 0 in other environments. The msqid, though, is of no use to other 
IPC routines, since the makeipc routine makes it available to them transparent to the user. 

If an error occurred, then the function will return a value of -1 and will set the variable 
dnet errno to indicate the error condition. 
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NAME 

prttime - return a string representing the current time of .by 
SYNOPSIS 

char *prttime() 

DESCRIPTION 

This internal library routine returns the current time of day in a character string of the form, 
"time: 12:59:59''. Hours, minutes, and seconds are given. 

RETURN VALUE 

This routine returns a pointer to the character string gent rated. 
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